Skip to content

Target Support Policy

Purpose

Define how agent-policy decides which tool compatibility targets to support, and in what order, without destabilizing the canonical policy schema.

Separation of Concerns

agent-policy uses three distinct concerns:

  1. Canonical policy semantics (agent-policy.yaml)

  2. Describes repository behavior: commands, paths, roles, constraints.

  3. Must remain tool-agnostic and stable.

  4. Output target selection (outputs and future target controls)

  5. Describes which compatibility artifacts are emitted.

  6. Must not leak tool-specific semantics into core policy rules.

  7. CLI runtime overrides

  8. Temporary command-time choices.

  9. Must never become hidden source-of-truth for CI.

Current v0.1 Contract

For v0.1.x, output targets are declared as an array of string IDs in the outputs field:

# outputs defaults to [agents-md] when omitted
outputs:
  - agents-md
  - claude-md # optional
  - cursor-rules # optional

Supported target IDs in v0.1: agents-md, claude-md, cursor-rules. Unknown IDs are rejected at normalization time with an explicit error. No profile or --targets override system is introduced in v0.1.

Target Classes

New target proposals are classified into one of four classes:

  1. Repo-scoped instruction files

  2. Example: AGENTS.md, CLAUDE.md, GEMINI.md.

  3. Repo-scoped rule/config directories

  4. Example: .cursor/rules/*.mdc, .github/instructions/*.instructions.md.

  5. Agent profile files

  6. Example: tool-specific agent profile documents under repo paths.

  7. Local or user-specific configuration

  8. Example: home-directory memory/settings files.

  9. Never generated by default for team repositories.

Support Tiers

Every target is assigned a tier in compatibility-matrix.md:

  1. Core

  2. Implemented, tested, and included in normal CI drift checks.

  3. Planned

  4. Explicitly accepted direction, not yet implemented.

  5. Experimental

  6. Behind feature flag or unstable interface; not part of default commitments.

  7. Reference-only

  8. Tracked for ecosystem awareness but intentionally not generated.

Admission Criteria for New Targets

A new target should be promoted only when all are true:

  1. Stable, documented repository file convention exists.
  2. The artifact is team-safe and committable to source control.
  3. Rendering can be deterministic and diff-checkable.
  4. The target adds clear incremental utility beyond existing outputs.
  5. Maintenance cost is acceptable (tests, docs, drift behavior, schema impact).

Schema Evolution Guardrail

Decision already made: outputs uses an array of string target IDs (outputs: [agents-md, claude-md]). Adding a new target requires only a new enum value in the JSON Schema — no structural migration, ever.

The design principle that drove this decision:

  1. Add concrete targets with explicit tests first.
  2. Prefer the schema shape that makes new targets additive by default (array > boolean map).
  3. Defer profiles and registry-backed metadata until target surface is stable (Phase 5+).

This keeps the migration path clean while avoiding the one-key-per-target schema sprawl that a boolean map would require.