Ref Sp Agents Policy

Swiftpost Agents Policy

Purpose

Document this repository's concrete AI policy implementation: the canonical policy file, the grouped agentic-tools policy CLI surface, the generated client outputs, and the service-selection model that decides which vendors receive managed files.

When to use this skill

• Working on the agents-policy feature or its generator logic.
• Updating policy docs, CI enforcement, or command references in this repo.
• Debugging why .aiexclude, .claude/settings.json, or .vscode/settings.json did or did not change.
• Explaining how the policy section in .agents/config.json should be authored in this repo.

Scope boundaries

This skill is the repo-local layer: how the agents-policy feature is actually built here — the .agents/config.json policy section, the sync command, and the generated vendor outputs.

• ref-sp-agents-security — the portable model behind it: protected vs excluded files, the multi-client enforcement story, and why the policy exists. Read that for the why, this for the how it is wired here.
• ref-sp-agents-skills-management — the other consumer of .agents/config.json. The two features share a config file, not a subject.
• ref-sp-dev-repo-conventions — where the feature's code belongs in this repo's layout.

Stable Surface

• Canonical policy file: .agents/config.json with a top-level policy object
• Canonical commands:
  • uv run agentic-tools policy sync
  • uv run agentic-tools policy check
  • uv run agentic-tools policy import-vscode
• Implemented as the agents-policy feature of the agentic-tools package (Python primary, with a legacy Node port); locate it by feature name rather than a fixed path while the package is being restructured.
• Packaged CLI entrypoint: agentic-tools; standalone policy bins are not exported.

Policy Model

The source-of-truth file is JSON. Its top-level policy object currently supports these main fields:

• services — list of enabled client outputs, such as gemini, claude, and copilot
• protectedFiles — sensitive patterns that should be blocked or deterred
• excludedFiles — noisy or generated patterns that should stay out of Gemini/native exclusion when enabled
• terminalAutoApprove — managed VS Code terminal approval map for Copilot-related tooling
• editAutoApprove — managed VS Code edit approval map

If services is omitted, the implementation defaults to all supported services.

Generated Outputs

Command Behavior

uv run agentic-tools policy sync

• Finds the nearest .agents/config.json with a policy object, with .agents/policy.json and legacy .ai-policy.json fallback.
• Loads the policy file, validates services, and syncs the enabled outputs.
• Cleans managed sections for disabled outputs so stale vendor files do not linger.

uv run agentic-tools policy check

• Resolves the same policy and generated output paths as the normal sync flow.
• Compares the current managed files to the generated contents without rewriting them.
• Exits with an error when drift exists and tells the user to run either uv run agentic-tools policy sync or uv run agentic-tools policy import-vscode.

uv run agentic-tools policy import-vscode

• Imports current VS Code approval maps into the policy section first.
• Writes the updated policy back to .agents/config.json when using unified config.
• Runs the same sync flow afterward.

Decision Rules

• Use .agents/config.json as the source of truth for new work.
• Prefer services to control vendor coverage instead of hand-editing generated files.
• Keep .aiexclude at the repo root; do not replace it with a made-up Gemini-only ignore file.
• Treat .claude/settings.json and .vscode/settings.json as partially managed outputs, not primary authoring surfaces for policy-owned sections.
• Keep docs and CI on the canonical agentic-tools policy command family; do not add standalone policy entrypoints.

Validation

• Run uv run agentic-tools policy sync after changing .agents/config.json or the sync implementation.
• Run uv run agentic-tools policy check in CI or before commit flows that should reject policy drift without mutating files.
• Run the agents-policy unit tests with uv run poe test (or target the feature's collocated *_test.py) when changing policy logic.
• Check CI drift enforcement in .github/workflows/ci.yaml if output file names or command names change.
• Keep .aiexclude, .claude/settings.json, and .vscode/settings.json aligned with the current policy file.

References

• Read ./references/checklist.md for a quick maintenance or debugging pass.
• Read ./references/config-shape.md for the current .agents/config.json policy contract.
• Read ./references/copilot.md, ./references/claude-code.md, and ./references/gemini.md for vendor-specific output details.
• Read .agents/skills/ref-sp-agents-security/SKILL.md for the portable concepts that sit above this repo's concrete implementation.
• Read ./assets/trigger-eval-queries.example.json when testing trigger quality for policy-tooling prompts.
• Review ./evals/evals.json when validating output quality for policy implementation explanations.