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.

Location · string

.aiox-core/project-config.yaml

Level · string

L2 (Project)

Mutability · string

Editable by project maintainers

Git Status · string

Committed to repository

Reference: ADR-PRO-002 — Configuration Hierarchy

Schema Reference

Project Metadata

project · object · required

Project installation metadata (project portion)

Show properties

type · string · required

Project type classification

• EXISTING_AIOX - Existing project with AIOX installed
• NEW_AIOX - New project using AIOX
• GREENFIELD - Greenfield project

installed_at · string · required

ISO 8601 installation timestamp

Example: "2025-01-14T00:00:00Z"

version · string · required

AIOX framework version for this project

Example: "2.1.0"

Documentation Paths

documentation_paths · object

Project documentation structure (Section 2)

Show properties

qa_dir · string · default: "docs/qa"

Quality assurance artifacts directory

prd_file · string · default: "docs/prd.md"

Product Requirements Document path

prd_version · string · default: "v4"

PRD template version

prd_sharded · boolean · default: "true"

Enable PRD sharding for large documents

prd_sharded_location · string · default: "docs/prd"

Directory for PRD shards

architecture_file · string · default: "docs/architecture.md"

Architecture documentation path

architecture_version · string · default: "v4"

Architecture doc version

architecture_sharded · boolean · default: "true"

Enable architecture sharding

architecture_sharded_location · string · default: "docs/architecture"

Directory for architecture shards

stories_dir · string · default: "docs/stories"

User stories directory

dev_debug_log · string · default: ".ai/debug-log.md"

Development debug log path

slash_prefix · string · default: "AIOX"

Command prefix for slash commands

dev_load_always_files · array

Files loaded by dev agent on activation

dev_load_always_files:
  - "docs/framework/coding-standards.md"
  - "docs/framework/tech-stack.md"
  - "docs/framework/source-tree.md"

GitHub Integration

github_integration · object

GitHub integration configuration (Section 8)

Show properties

enabled · boolean · default: "true"

Enable GitHub integration

cli_required · boolean · default: "false"

Require GitHub CLI (gh) for operations

features · object

Feature flags

features:
  pr_creation: true
  issue_management: true

pr · object

Pull request configuration

Show pr properties

title_format · string · default: "conventional"

PR title format: conventional, simple

include_story_id · boolean · default: "true"

Include story ID in PR title

conventional_commits · object

Conventional commits settings

conventional_commits:
  enabled: true
  branch_type_map:
    "feature/": "feat"
    "fix/": "fix"
    "docs/": "docs"
  default_type: "feat"

auto_assign_reviewers · boolean · default: "false"

Automatically assign reviewers to PRs

draft_by_default · boolean · default: "false"

Create PRs as drafts by default

semantic_release · object

Semantic release configuration

semantic_release:
  enabled: true

CodeRabbit Integration

coderabbit_integration · object

CodeRabbit AI code review integration (Section 9)

Show properties

enabled · boolean · default: "true"

Enable CodeRabbit integration

self_healing · object

Self-healing configuration

self_healing:
  enabled: true
  type: "full"  # or "partial"
  max_iterations: 3
  timeout_minutes: 30

severity_handling · object

Issue severity handling rules

severity_handling:
  CRITICAL: "auto_fix"
  HIGH: "auto_fix"
  MEDIUM: "document_as_debt"
  LOW: "ignore"

graceful_degradation · object

Graceful degradation settings

graceful_degradation:
  skip_if_not_installed: true
  fallback_message: "CodeRabbit CLI not found..."

report_location · string · default: "docs/qa/coderabbit-reports/"

Directory for CodeRabbit reports

Squads System

squads · object

Agent squad configuration (Section 10)

Show properties

template_location · string · default: "templates/squad"

Squad template directory

auto_load · boolean · default: "false"

Automatically load squads on activation

Logging & Status

logging · object

Logging and status configuration (Section 7)

Show properties

decision_logging · object

Architecture Decision Record logging

decision_logging:
  enabled: true
  async: true
  location: ".ai/"
  index_file: "decision-logs-index.md"
  format: "adr"
  performance:
    max_overhead: 50

project_status · object

Project status tracking

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

agent_identity · object

Agent identity and greeting settings

agent_identity:
  greeting:
    context_detection: true
    session_detection: "hybrid"
    workflow_detection: "hardcoded"
    performance:
      git_check_cache: true
      git_check_ttl: 300

Additional Features

story_backlog · object

Story backlog management

story_backlog:
  enabled: true
  location: "docs/stories/backlog"
  prioritization: "value_risk"

pv_mind_context · object

PV Mind Context (personal voice/persona system)

pv_mind_context:
  enabled: true
  location: "outputs/minds/pedro_valerio"
  features:
    persona_voice: true
    technical_depth: "advanced"
    communication_style: "structured"

auto_claude · object

Auto-Claude automation configuration (Section 13)

Show properties

enabled · boolean · default: "true"

Enable Auto-Claude features

version · string · default: "3.0"

Auto-Claude version

worktree · object

Git worktree configuration

worktree:
  enabled: true
  auto_create: "on_story_start"
  auto_cleanup: "manual"
  max_worktrees: 10
  stale_days: 30
  branch_prefix: "auto-claude/"

spec_pipeline · object

Specification pipeline settings

spec_pipeline:
  enabled: false

Example Configuration

# ============================================
# 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

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

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

Security

• Never commit secrets or API keys
• Use environment variables for sensitive data
• Document required environment variables
• Use local-config.yaml for personal credentials

Related Documentation

• Configuration Files Overview
• Core Config Schema
• Framework Config Schema
• Configuration Best Practices

---

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