Skip to content

README.md

Latest commit

 

History

History
50 lines (40 loc) · 2.7 KB

README.md

File metadata and controls

50 lines (40 loc) · 2.7 KB

AI Agent Configuration & Policy Template

This repository is a central infrastructure for managing AI agent behavior across VS Code Copilot and Codex. It enforces a "Fail-Fast" engineering culture, ensuring that AI-assisted development is deterministic, secure, and accurate.

1. What is this?

This is a configuration and policy framework designed to standardize how AI agents interact with my codebase. It is not an application runtime; rather, it is a set of instructions, role definitions, and reusable prompts that govern agent autonomy.

Core Components:

  • AGENTS.md: The "Cross-Agent Spine" and normative source of truth for all agent priorities and safety boundaries.
  • Copilot Config (.github/): Custom instructions (.instructions.md), agent profiles (.agent.md), and reusable slash-command prompts (.prompt.md).
  • Codex Config (.codex/): TOML-based role mappings and execution policies for the Codex platform.

2. What does it help with?

This template solves common "AI drift" and safety issues by providing:

  • Platform Parity: Ensures the same rules (Python, Security, Testing) apply whether you use VS Code Copilot or Codex.
  • Fail-Fast Error Handling: Prevents agents from silently failing or returning hallucinated defaults; errors are surfaced with actionable context.
  • Sensitive Path Gating: Automatically flags high-risk areas (e.g., .github/workflows, infra/, secrets/) for explicit developer confirmation.
  • Structured Workflows: Provides off-the-shelf agents for specific phases: Planner (architecting), Implementer (coding), and Reviewer (quality gate).
  • Reduced Hallucination: Enforces grounding by requiring agents to inspect actual project configs and call-sites before proposing edits.

3. How to install and use

Follow these steps to integrate this policy engine into your project.

Installation

  1. Copy the Scaffolding: Copy the following directories and files to your target repository root:
    • AGENTS.md
    • .github/
    • .codex/ (if using Codex)
    • scripts/
  2. Setup Prerequisites: Ensure you have Node.js (v20+) installed for validation.
  3. Verify Local Setup: 
    node scripts/validate-copilot-files.mjs
node scripts/validate-codex-files.mjs

Daily Usage

  • In VS Code Copilot:
    • Use Slash Commands: Trigger commands directly from the chat.
  • In Codex:
    • The project will automatically load policies from .codex/config.toml once the workspace is trusted.
  • Maintaining Policy:
    • Update AGENTS.md whenever you add new sensitive paths or core engineering priorities.
    • Run the validation scripts before committing any changes to instruction or prompt files.