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..aiox-core/project-config.yaml
Editable by project maintainers
Reference: ADR-PRO-002 — Configuration Hierarchy
Schema Reference Project installation metadata (project portion) Project type classification
EXISTING_AIOX - Existing project with AIOX installedNEW_AIOX - New project using AIOXGREENFIELD - Greenfield project ISO 8601 installation timestamp Example: "2025-01-14T00:00:00Z"
AIOX framework version for this project Example: "2.1.0"
Documentation Paths Project documentation structure (Section 2) Quality assurance artifacts directory
prd_file
string
default: "docs/prd.md"
Product Requirements Document path
Enable PRD sharding for large documents
architecture_file
string
default: "docs/architecture.md"
Architecture documentation path
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
Command prefix for slash commands
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 configuration (Section 8) Enable GitHub integration
Require GitHub CLI (gh) for operations
Feature flags features : pr_creation : true issue_management : true
Pull request configuration title_format
string
default: "conventional"
PR title format: conventional, simple
Include story ID in PR title
Conventional commits settings conventional_commits : enabled : true branch_type_map : "feature/" : "feat" "fix/" : "fix" "docs/" : "docs" default_type : "feat"
Automatically assign reviewers to PRs
Create PRs as drafts by default
Semantic release configuration semantic_release : enabled : true
CodeRabbit Integration CodeRabbit AI code review integration (Section 9) Enable CodeRabbit integration
Self-healing configuration self_healing : enabled : true type : "full" # or "partial" max_iterations : 3 timeout_minutes : 30
Issue severity handling rules severity_handling : CRITICAL : "auto_fix" HIGH : "auto_fix" MEDIUM : "document_as_debt" LOW : "ignore"
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 Agent squad configuration (Section 10) template_location
string
default: "templates/squad"
Squad template directory
Automatically load squads on activation
Logging & Status Logging and status configuration (Section 7) 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 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 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 management story_backlog : enabled : true location : "docs/stories/backlog" prioritization : "value_risk"
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 automation configuration (Section 13) Enable Auto-Claude features
Git worktree configuration worktree : enabled : true auto_create : "on_story_start" auto_cleanup : "manual" max_worktrees : 10 stale_days : 30 branch_prefix : "auto-claude/"
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
Commit project-config.yaml to repository
Document all project-specific customizations
Review changes in PRs like any other code
Keep settings minimal and intentional
Override framework defaults only when necessary
Use descriptive comments for complex settings
Test configuration changes in isolation
Maintain backward compatibility for team members
Never commit secrets or API keys
Use environment variables for sensitive data
Document required environment variables
Use local-config.yaml for personal credentials
Reference: .aiox-core/project-config.yaml | ADR-PRO-002 