project-config

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://schema-atoms.com/schemas/project-config/1.0.0/project-config.json",
  "title": "Project AI Configuration (project.yaml)",
  "description": "Schema for the project.yaml AI configuration file used across all convergent-systems-co repositories. Governs how Olympus, Claude Code, and related AI tooling behave in a project: language conventions, test commands, governance policy, review panels, and optional Azure DevOps integration.",
  "type": "object",
  "additionalProperties": true,
  "properties": {
    "name": {
      "type": "string",
      "minLength": 1,
      "maxLength": 120,
      "description": "Human-readable project name. Should match the repository slug."
    },
    "language": {
      "type": "string",
      "description": "Primary programming language (singular form). Use `languages` for multi-language repos.",
      "examples": ["go", "typescript", "python", "terraform", "markdown"]
    },
    "languages": {
      "type": "array",
      "items": { "type": "string", "minLength": 1 },
      "uniqueItems": true,
      "description": "List of programming languages when the repo is multi-language."
    },
    "framework": {
      "type": "string",
      "description": "Primary framework. Use empty string or 'none' when not applicable.",
      "examples": ["chi", "gin", "echo", "stdlib", "none", ""]
    },
    "personas": {
      "type": "array",
      "items": { "type": "string", "minLength": 1 },
      "uniqueItems": true,
      "description": "List of persona definition file paths (relative to repo root) activated for this project. Personas shape how AI agents reason and communicate.",
      "examples": [
        ["quality/code-reviewer.md", "engineering/test-engineer.md", "compliance/security-auditor.md"]
      ]
    },
    "panels": {
      "$ref": "https://schema-atoms.com/schemas/panels-config/1.0.0/panels-config.json",
      "description": "Review panels to run on every change. See panels-config schema for item shape."
    },
    "paths": {
      "type": "object",
      "description": "Canonical directory paths for AI-generated artifacts.",
      "additionalProperties": false,
      "properties": {
        "plans":       { "type": "string", "description": "Directory for implementation plans." },
        "decisions":   { "type": "string", "description": "Directory for ADR / decision records." },
        "checkpoints": { "type": "string", "description": "Directory for session checkpoint files." }
      }
    },
    "tooling": {
      "type": "object",
      "description": "Build and quality tooling commands used by AI agents and CI.",
      "additionalProperties": false,
      "properties": {
        "test_command":  { "type": "string", "description": "Command to run the full test suite.", "examples": ["go test ./...", "pytest", "npm test", "terraform test"] },
        "lint_command":  { "type": "string", "description": "Command to run linting.", "examples": ["golangci-lint run", "eslint .", "terraform fmt -check -recursive"] },
        "build_command": { "type": "string", "description": "Command to produce the distributable artifact." },
        "pre_commit":    { "type": "boolean", "description": "Whether pre-commit hooks are enabled in this repo." },
        "lfs":           { "type": "boolean", "description": "Whether Git LFS is used in this repo." }
      }
    },
    "conventions": {
      "type": "object",
      "description": "Project-level coding, testing, style, and git conventions.",
      "additionalProperties": true,
      "properties": {
        "testing": {
          "type": "object",
          "additionalProperties": true,
          "properties": {
            "framework":        { "type": "string", "description": "Test framework name.", "examples": ["go test", "pytest", "jest", "xunit"] },
            "assertions":       { "type": "string", "description": "Assertion library or style.", "examples": ["stdlib", "testify", "chai"] },
            "naming":           { "type": "string", "description": "Test naming convention.", "examples": ["TestFunctionName_Scenario", "it_describes_behavior"] },
            "pattern":          { "type": "string", "description": "Preferred test pattern.", "examples": ["table-driven", "bdd", "unit"] },
            "coverage_target":  { "type": "integer", "minimum": 0, "maximum": 100, "description": "Minimum line coverage percentage." }
          }
        },
        "style": {
          "type": "object",
          "additionalProperties": true,
          "properties": {
            "formatter": { "type": "string", "description": "Code formatter.", "examples": ["gofmt", "prettier", "black"] },
            "linter":    { "type": "string", "description": "Linter.", "examples": ["golangci-lint", "eslint", "ruff"] },
            "indent":    { "type": "string", "enum": ["tabs", "spaces"], "description": "Indentation style." }
          }
        },
        "architecture": {
          "type": "object",
          "additionalProperties": true,
          "properties": {
            "layout":         { "type": "string", "description": "Directory layout convention.", "examples": ["standard", "flat", "hexagonal"] },
            "error_handling": { "type": "string", "description": "Error handling pattern.", "examples": ["wrap", "sentinel", "result"] }
          }
        },
        "git": {
          "type": "object",
          "additionalProperties": true,
          "properties": {
            "branch_pattern": { "type": "string", "description": "Branch naming pattern.", "examples": ["{type}/{issue}-{description}", "feature/{ticket}-{description}"] },
            "commit_style":   { "type": "string", "enum": ["conventional", "free-form"], "description": "Commit message style." },
            "pr_template":    { "type": "boolean", "description": "Whether a PR body template is in use." }
          }
        }
      }
    },
    "governance": {
      "type": "object",
      "description": "Olympus governance settings for this project.",
      "additionalProperties": true,
      "properties": {
        "policy_profile":      { "type": "string", "description": "Named governance policy profile to apply.", "examples": ["default", "strict", "minimal"] },
        "parallel_tech_leads": { "type": "integer", "minimum": 1, "description": "Number of parallel tech-lead agents to spawn." },
        "parallel_coders":     { "type": "integer", "minimum": 1, "description": "Number of parallel coder agents to spawn." },
        "require_worktree":    { "type": "boolean", "description": "Enforce that all work happens in a git worktree, never on the main working tree." },
        "require_tdd":         { "type": "boolean", "description": "Enforce TDD writer before coder for every story." },
        "llm_backend":         { "type": "string", "enum": ["claude", "openai", "local"], "description": "LLM provider for governance pipeline agents." },
        "use_project_manager": { "type": "boolean", "description": "Whether to include a project-manager agent in the dispatch pipeline." }
      }
    },
    "repository": {
      "type": "object",
      "description": "GitHub repository behaviour settings.",
      "additionalProperties": false,
      "properties": {
        "auto_merge":             { "type": "boolean", "description": "Enable GitHub auto-merge on PRs that pass all checks." },
        "delete_branch_on_merge": { "type": "boolean", "description": "Delete the source branch after a PR is merged." },
        "codeowners": {
          "type": "object",
          "additionalProperties": false,
          "properties": {
            "enabled": { "type": "boolean", "description": "Whether CODEOWNERS file enforcement is active." }
          }
        }
      }
    },
    "issue_tracker": {
      "type": "object",
      "description": "Issue tracking provider configuration.",
      "additionalProperties": false,
      "required": ["provider"],
      "properties": {
        "provider": {
          "type": "string",
          "description": "One or more issue tracking providers (comma-separated for multi-provider).",
          "examples": ["issues", "ado", "issues, ado"]
        },
        "bidirectional": {
          "type": "boolean",
          "description": "Sync in both directions when multiple providers are configured."
        }
      }
    },
    "ado_integration": {
      "type": "object",
      "description": "Azure DevOps integration configuration.",
      "additionalProperties": true,
      "required": ["schema_version", "enabled", "organization", "project"],
      "properties": {
        "schema_version": { "type": "string", "description": "ADO integration schema version.", "const": "1.0.0" },
        "enabled":        { "type": "boolean", "description": "Activate the ADO integration." },
        "organization":   { "type": "string", "format": "uri", "description": "Azure DevOps organization URL." },
        "project":        { "type": "string", "description": "Azure DevOps project name." },
        "auth_method":    { "type": "string", "enum": ["pat", "oauth", "managed-identity"], "description": "Authentication method." },
        "auth_secret_name": { "type": "string", "description": "Name of the environment variable or secret holding the auth credential." }
      }
    },
    "instructions": {
      "type": "string",
      "description": "Free-form project-specific instructions injected into AI agent system prompts for this project.",
      "maxLength": 4096
    },
    "project_name": {
      "type": "string",
      "minLength": 1,
      "maxLength": 120,
      "description": "Alternative project name field; some templates use `project_name` alongside `name`. Prefer `name`."
    }
  },
  "examples": [
    {
      "name": "core-infra",
      "languages": ["markdown", "terraform"],
      "framework": "none",
      "paths": { "plans": "docs/plans", "decisions": "docs/decisions", "checkpoints": "docs/checkpoints" },
      "tooling": { "test_command": "terraform test", "lint_command": "terraform fmt -check -recursive", "pre_commit": false, "lfs": false },
      "conventions": { "git": { "branch_pattern": "{type}/{issue}-{description}", "commit_style": "conventional" } },
      "governance": { "policy_profile": "default", "parallel_tech_leads": 3, "parallel_coders": 5, "require_worktree": true, "require_tdd": false, "llm_backend": "claude" },
      "panels": ["code-review", "security-review", "architecture-review"],
      "repository": { "auto_merge": false, "delete_branch_on_merge": true, "codeowners": { "enabled": false } },
      "issue_tracker": { "provider": "issues" }
    }
  ]
}