Agentic Project Governance

Agentic Project Governance#

Repository Specification — v1.0.0#

Status: Initial public release
Working repository name: agentic-project-governance
Short name: APG (provisional)
Specification version: 1.0 Guide revision: 2026-08-17
Primary goal: Define a vendor-neutral, repository-native governance structure for human–AI project work.

APG at a Glance#

APG is the approved project governance contract: a vendor-neutral, repository-native framework that defines how sources, rules, authority, and validation are declared and resolved. APG is applied to a project; it is not the project, an agent, or an executable system.

APG is a governance contract and standardization framework, not an official industry standard. It standardizes how governance is declared and resolved, not how every project must operate.

The manifest is not an agent, MCP server, workflow engine, prompt, database, executable system, or infrastructure inventory.

The small APG core answers four questions:

1. What is authoritative?
2. Which rules apply here?
3. What is allowed?
4. What proves the result?

That core is Sources, Rules, Authority, and Validation / Evidence. It is designed to remain explicit, repeatable, verifiable, vendor-neutral, human-approved, and repository-native.

APG references existing authoritative project facts and owns the governance contract around them.

For example, a project might declare docs/SDS.xlsx authoritative for infrastructure inventory, docs/architecture.md for architecture, VERSION for release identity, and .gitlab-ci.yml for deployment automation.

README.md:      PRD = srv-old
docs/SDS.xlsx:  PRD = srv-03

If the manifest declares docs/SDS.xlsx authoritative for infrastructure, every consumer must resolve PRD = srv-03 from that file. The manifest references project truth; it does not copy the inventory.

Codex, Claude, Gemini, and other AI systems may discover, propose, generate, consume, and validate. They are not themselves the governance authority. Humans or existing authoritative organizational mechanisms resolve and approve organizational facts and authority decisions.

UNRESOLVED:
Production deployment authority is not defined.
Human or authoritative-source resolution required.

Do not infer an approver. The simple lifecycle is:

Discover → Propose → Human / authoritative resolution
→ Approve → Record → Validate → Reuse

APG does not require identical prose from different tools. Given the same approved contract, consumers should resolve the same fact, source, rule, authority, validation requirement, and governance decision. Different wording is acceptable; contradictory governance interpretation is not.

APG is most useful where governance ambiguity creates operational risk: medium-sized businesses, larger organizations, multi-team projects, production-critical or regulated environments, external-vendor work, distributed documentation and ownership, or environments using multiple AI systems and automation tools.

APG is not for every repository. A README.md or AGENTS.md may be sufficient for a small personal project, prototype, temporary experiment, or simple single-developer repository. AI use alone is not a reason to adopt APG.

APG does not require GitFlow, Jira, Kubernetes, GitHub, GitLab, any specific AI vendor, an SDS, or any specific organizational structure.

APG should be introduced when the cost of ambiguity becomes higher than the cost of governance.

1. Executive Summary#

Modern AI coding and work agents already support persistent project instructions, scoped instructions, reusable skills, and repository context. The problem is that each tool exposes these capabilities differently, and projects often mix policy, project knowledge, workflow instructions, role behavior, and task context into one large prompt or one vendor-specific file.

Agentic Project Governance (APG) proposes a small, portable project contract that lives with the repository.

The framework is not an AI model, agent runtime, orchestration platform, prompt library, or replacement for CI/CD. It is a structure for making a project understandable and governable by humans and AI agents.

The core idea is:

flowchart TB
    G["APG Canonical Governance"]

    G --> C["Codex Adapter"]
    G --> CL["Claude Adapter"]
    G --> GM["Gemini Adapter"]
    G --> CP["Copilot Adapter"]

    C --> A["AGENTS.md"]
    CL --> CM["CLAUDE.md"]
    GM --> GMM["GEMINI.md"]
    CP --> CI["copilot-instructions.md"]

    classDef governance fill:#123d27,stroke:#38c976,stroke-width:2px,color:#ffffff;
    classDef adapter fill:#16231b,stroke:#5d876b,stroke-width:1.5px,color:#ffffff;
    classDef file fill:#0b100d,stroke:#385243,stroke-width:1px,color:#dce8df;

    class G governance;
    class C,CL,GM,CP adapter;
    class A,CM,GMM,CI file;

A model or tool may change. The project contract should remain.

1.1 Start Here — What This Actually Does#

If this is your first time reading APG, do not begin by thinking about AGENTS.md, AI models, prompts, or tooling.

Start with a simpler question:

How should a project explain its rules, context, responsibilities, and proof of completion so that both humans and AI agents can work on it consistently?

APG gives that information a predictable home inside the repository.

A project using APG should make it possible for a new human or AI agent to answer:

flowchart TB
    G["APG Canonical Governance"]

    G --> C["Codex Adapter"]
    G --> CL["Claude Adapter"]
    G --> GM["Gemini Adapter"]
    G --> CP["Copilot Adapter"]

    C --> A["AGENTS.md"]
    CL --> CM["CLAUDE.md"]
    GM --> GMM["GEMINI.md"]
    CP --> CI["copilot-instructions.md"]

    classDef governance fill:#123d27,stroke:#38c976,stroke-width:2px,color:#ffffff;
    classDef adapter fill:#16231b,stroke:#5d876b,stroke-width:1.5px,color:#ffffff;
    classDef file fill:#0b100d,stroke:#385243,stroke-width:1px,color:#dce8df;

    class G governance;
    class C,CL,GM,CP adapter;
    class A,CM,GMM,CI file;

The framework does not decide the business logic for you.

It gives you a structure in which your own business, engineering, operational, legal, HR, process, or technical rules can be expressed consistently.

Think of APG as a project operating system#

A useful mental model is:

flowchart TB
    G["APG Canonical Governance"]

    G --> C["Codex Adapter"]
    G --> CL["Claude Adapter"]
    G --> GM["Gemini Adapter"]
    G --> CP["Copilot Adapter"]

    C --> A["AGENTS.md"]
    CL --> CM["CLAUDE.md"]
    GM --> GMM["GEMINI.md"]
    CP --> CI["copilot-instructions.md"]

    classDef governance fill:#123d27,stroke:#38c976,stroke-width:2px,color:#ffffff;
    classDef adapter fill:#16231b,stroke:#5d876b,stroke-width:1.5px,color:#ffffff;
    classDef file fill:#0b100d,stroke:#385243,stroke-width:1px,color:#dce8df;

    class G governance;
    class C,CL,GM,CP adapter;
    class A,CM,GMM,CI file;

The AI model is not the system of record.

The project repository is.

1.2 Who Can Use APG?#

APG is intentionally domain-neutral.

It can be used anywhere a project has:

• rules;
• context;
• recurring procedures;
• responsibilities;
• approval boundaries;
• validation requirements;
• handover needs;
• multiple people or AI agents working over time.

This includes software engineering, DevOps, infrastructure, operations, HR, industrial engineering, research, finance, documentation, compliance, product work, data engineering, and many other domains.

The project does not need to produce code.

It only needs work that benefits from explicit structure and repeatability.

1.3 Example — DevOps and Infrastructure Automation#

Scenario#

A platform team manages:

• Linux servers;
• Ansible automation;
• Docker;
• Kubernetes;
• CI/CD;
• production deployments;
• security hardening;
• change windows.

Without governance, an AI agent may know how to generate an Ansible playbook but still not know:

• which inventory is authoritative;
• whether production changes are allowed;
• whether canary execution is required;
• what validation must run;
• whether restarts require approval;
• where secrets must come from;
• how rollback must be documented.

APG project structure#

flowchart TB
    G["APG Canonical Governance"]

    G --> C["Codex Adapter"]
    G --> CL["Claude Adapter"]
    G --> GM["Gemini Adapter"]
    G --> CP["Copilot Adapter"]

    C --> A["AGENTS.md"]
    CL --> CM["CLAUDE.md"]
    GM --> GMM["GEMINI.md"]
    CP --> CI["copilot-instructions.md"]

    classDef governance fill:#123d27,stroke:#38c976,stroke-width:2px,color:#ffffff;
    classDef adapter fill:#16231b,stroke:#5d876b,stroke-width:1.5px,color:#ffffff;
    classDef file fill:#0b100d,stroke:#385243,stroke-width:1px,color:#dce8df;

    class G governance;
    class C,CL,GM,CP adapter;
    class A,CM,GMM,CI file;

What the agent learns#

flowchart TB
    G["APG Canonical Governance"]

    G --> C["Codex Adapter"]
    G --> CL["Claude Adapter"]
    G --> GM["Gemini Adapter"]
    G --> CP["Copilot Adapter"]

    C --> A["AGENTS.md"]
    CL --> CM["CLAUDE.md"]
    GM --> GMM["GEMINI.md"]
    CP --> CI["copilot-instructions.md"]

    classDef governance fill:#123d27,stroke:#38c976,stroke-width:2px,color:#ffffff;
    classDef adapter fill:#16231b,stroke:#5d876b,stroke-width:1.5px,color:#ffffff;
    classDef file fill:#0b100d,stroke:#385243,stroke-width:1px,color:#dce8df;

    class G governance;
    class C,CL,GM,CP adapter;
    class A,CM,GMM,CI file;

Now the agent is not only capable of generating automation.

It understands how automation must be produced and operated inside this specific project.

1.4 Example — Software Product Development#

Scenario#

A company is building a SaaS application with:

• frontend;
• backend;
• API;
• tests;
• release automation;
• security requirements.

Different teams and agents work on different areas.

Structure#

flowchart TB
    G["APG Canonical Governance"]

    G --> C["Codex Adapter"]
    G --> CL["Claude Adapter"]
    G --> GM["Gemini Adapter"]
    G --> CP["Copilot Adapter"]

    C --> A["AGENTS.md"]
    CL --> CM["CLAUDE.md"]
    GM --> GMM["GEMINI.md"]
    CP --> CI["copilot-instructions.md"]

    classDef governance fill:#123d27,stroke:#38c976,stroke-width:2px,color:#ffffff;
    classDef adapter fill:#16231b,stroke:#5d876b,stroke-width:1.5px,color:#ffffff;
    classDef file fill:#0b100d,stroke:#385243,stroke-width:1px,color:#dce8df;

    class G governance;
    class C,CL,GM,CP adapter;
    class A,CM,GMM,CI file;

Example scoped behavior#

The root project may define:

flowchart TB
    G["APG Canonical Governance"]

    G --> C["Codex Adapter"]
    G --> CL["Claude Adapter"]
    G --> GM["Gemini Adapter"]
    G --> CP["Copilot Adapter"]

    C --> A["AGENTS.md"]
    CL --> CM["CLAUDE.md"]
    GM --> GMM["GEMINI.md"]
    CP --> CI["copilot-instructions.md"]

    classDef governance fill:#123d27,stroke:#38c976,stroke-width:2px,color:#ffffff;
    classDef adapter fill:#16231b,stroke:#5d876b,stroke-width:1.5px,color:#ffffff;
    classDef file fill:#0b100d,stroke:#385243,stroke-width:1px,color:#dce8df;

    class G governance;
    class C,CL,GM,CP adapter;
    class A,CM,GMM,CI file;

The backend subtree may add:

flowchart TB
    G["APG Canonical Governance"]

    G --> C["Codex Adapter"]
    G --> CL["Claude Adapter"]
    G --> GM["Gemini Adapter"]
    G --> CP["Copilot Adapter"]

    C --> A["AGENTS.md"]
    CL --> CM["CLAUDE.md"]
    GM --> GMM["GEMINI.md"]
    CP --> CI["copilot-instructions.md"]

    classDef governance fill:#123d27,stroke:#38c976,stroke-width:2px,color:#ffffff;
    classDef adapter fill:#16231b,stroke:#5d876b,stroke-width:1.5px,color:#ffffff;
    classDef file fill:#0b100d,stroke:#385243,stroke-width:1px,color:#dce8df;

    class G governance;
    class C,CL,GM,CP adapter;
    class A,CM,GMM,CI file;

The frontend subtree may instead add:

flowchart TB
    G["APG Canonical Governance"]

    G --> C["Codex Adapter"]
    G --> CL["Claude Adapter"]
    G --> GM["Gemini Adapter"]
    G --> CP["Copilot Adapter"]

    C --> A["AGENTS.md"]
    CL --> CM["CLAUDE.md"]
    GM --> GMM["GEMINI.md"]
    CP --> CI["copilot-instructions.md"]

    classDef governance fill:#123d27,stroke:#38c976,stroke-width:2px,color:#ffffff;
    classDef adapter fill:#16231b,stroke:#5d876b,stroke-width:1.5px,color:#ffffff;
    classDef file fill:#0b100d,stroke:#385243,stroke-width:1px,color:#dce8df;

    class G governance;
    class C,CL,GM,CP adapter;
    class A,CM,GMM,CI file;

One project contract, different local rules.

1.5 Example — Human Resources and Recruitment#

APG is not limited to engineering.

Scenario#

An HR team uses AI to help with:

• job descriptions;
• candidate screening;
• interview preparation;
• interview summaries;
• hiring recommendations;
• onboarding documents.

The main risk is not deployment.

The risk is inconsistency, privacy, bias, authority, and unclear decision ownership.

Structure#

flowchart TB
    G["APG Canonical Governance"]

    G --> C["Codex Adapter"]
    G --> CL["Claude Adapter"]
    G --> GM["Gemini Adapter"]
    G --> CP["Copilot Adapter"]

    C --> A["AGENTS.md"]
    CL --> CM["CLAUDE.md"]
    GM --> GMM["GEMINI.md"]
    CP --> CI["copilot-instructions.md"]

    classDef governance fill:#123d27,stroke:#38c976,stroke-width:2px,color:#ffffff;
    classDef adapter fill:#16231b,stroke:#5d876b,stroke-width:1.5px,color:#ffffff;
    classDef file fill:#0b100d,stroke:#385243,stroke-width:1px,color:#dce8df;

    class G governance;
    class C,CL,GM,CP adapter;
    class A,CM,GMM,CI file;

Governance examples#

flowchart TB
    G["APG Canonical Governance"]

    G --> C["Codex Adapter"]
    G --> CL["Claude Adapter"]
    G --> GM["Gemini Adapter"]
    G --> CP["Copilot Adapter"]

    C --> A["AGENTS.md"]
    CL --> CM["CLAUDE.md"]
    GM --> GMM["GEMINI.md"]
    CP --> CI["copilot-instructions.md"]

    classDef governance fill:#123d27,stroke:#38c976,stroke-width:2px,color:#ffffff;
    classDef adapter fill:#16231b,stroke:#5d876b,stroke-width:1.5px,color:#ffffff;
    classDef file fill:#0b100d,stroke:#385243,stroke-width:1px,color:#dce8df;

    class G governance;
    class C,CL,GM,CP adapter;
    class A,CM,GMM,CI file;

The same APG concepts still work:

flowchart TB
    G["APG Canonical Governance"]

    G --> C["Codex Adapter"]
    G --> CL["Claude Adapter"]
    G --> GM["Gemini Adapter"]
    G --> CP["Copilot Adapter"]

    C --> A["AGENTS.md"]
    CL --> CM["CLAUDE.md"]
    GM --> GMM["GEMINI.md"]
    CP --> CI["copilot-instructions.md"]

    classDef governance fill:#123d27,stroke:#38c976,stroke-width:2px,color:#ffffff;
    classDef adapter fill:#16231b,stroke:#5d876b,stroke-width:1.5px,color:#ffffff;
    classDef file fill:#0b100d,stroke:#385243,stroke-width:1px,color:#dce8df;

    class G governance;
    class C,CL,GM,CP adapter;
    class A,CM,GMM,CI file;

Only the business domain changes.

1.6 Example — Industrial Engineering and Process Improvement#

Scenario#

An industrial engineering team is optimizing a production or service process.

Work may include:

• process mapping;
• time studies;
• capacity analysis;
• bottleneck detection;
• standard work;
• root-cause analysis;
• continuous improvement;
• SOP generation;
• KPI review.

Structure#

flowchart TB
    G["APG Canonical Governance"]

    G --> C["Codex Adapter"]
    G --> CL["Claude Adapter"]
    G --> GM["Gemini Adapter"]
    G --> CP["Copilot Adapter"]

    C --> A["AGENTS.md"]
    CL --> CM["CLAUDE.md"]
    GM --> GMM["GEMINI.md"]
    CP --> CI["copilot-instructions.md"]

    classDef governance fill:#123d27,stroke:#38c976,stroke-width:2px,color:#ffffff;
    classDef adapter fill:#16231b,stroke:#5d876b,stroke-width:1.5px,color:#ffffff;
    classDef file fill:#0b100d,stroke:#385243,stroke-width:1px,color:#dce8df;

    class G governance;
    class C,CL,GM,CP adapter;
    class A,CM,GMM,CI file;

Example workflow#

flowchart TB
    G["APG Canonical Governance"]

    G --> C["Codex Adapter"]
    G --> CL["Claude Adapter"]
    G --> GM["Gemini Adapter"]
    G --> CP["Copilot Adapter"]

    C --> A["AGENTS.md"]
    CL --> CM["CLAUDE.md"]
    GM --> GMM["GEMINI.md"]
    CP --> CI["copilot-instructions.md"]

    classDef governance fill:#123d27,stroke:#38c976,stroke-width:2px,color:#ffffff;
    classDef adapter fill:#16231b,stroke:#5d876b,stroke-width:1.5px,color:#ffffff;
    classDef file fill:#0b100d,stroke:#385243,stroke-width:1px,color:#dce8df;

    class G governance;
    class C,CL,GM,CP adapter;
    class A,CM,GMM,CI file;

An AI agent can help calculate, analyze, document, or propose changes, but the project governance defines:

• which measurements are authoritative;
• which safety constraints cannot be bypassed;
• who approves a process change;
• which KPIs prove improvement;
• when a pilot is required.

This is the same governance problem as infrastructure automation, expressed in a different domain.

1.7 Example — Business Operations#

Scenario#

A business operations team manages recurring work such as:

• vendor onboarding;
• purchasing;
• service requests;
• approvals;
• customer escalation;
• internal reporting;
• operational checklists.

Possible structure#

flowchart TB
    G["APG Canonical Governance"]

    G --> C["Codex Adapter"]
    G --> CL["Claude Adapter"]
    G --> GM["Gemini Adapter"]
    G --> CP["Copilot Adapter"]

    C --> A["AGENTS.md"]
    CL --> CM["CLAUDE.md"]
    GM --> GMM["GEMINI.md"]
    CP --> CI["copilot-instructions.md"]

    classDef governance fill:#123d27,stroke:#38c976,stroke-width:2px,color:#ffffff;
    classDef adapter fill:#16231b,stroke:#5d876b,stroke-width:1.5px,color:#ffffff;
    classDef file fill:#0b100d,stroke:#385243,stroke-width:1px,color:#dce8df;

    class G governance;
    class C,CL,GM,CP adapter;
    class A,CM,GMM,CI file;

APG can make it explicit that:

flowchart TB
    G["APG Canonical Governance"]

    G --> C["Codex Adapter"]
    G --> CL["Claude Adapter"]
    G --> GM["Gemini Adapter"]
    G --> CP["Copilot Adapter"]

    C --> A["AGENTS.md"]
    CL --> CM["CLAUDE.md"]
    GM --> GMM["GEMINI.md"]
    CP --> CI["copilot-instructions.md"]

    classDef governance fill:#123d27,stroke:#38c976,stroke-width:2px,color:#ffffff;
    classDef adapter fill:#16231b,stroke:#5d876b,stroke-width:1.5px,color:#ffffff;
    classDef file fill:#0b100d,stroke:#385243,stroke-width:1px,color:#dce8df;

    class G governance;
    class C,CL,GM,CP adapter;
    class A,CM,GMM,CI file;

1.8 Example — Data and Analytics#

Scenario#

A data team uses AI for:

• SQL generation;
• ETL/ELT changes;
• KPI calculations;
• dashboard development;
• data quality analysis;
• reporting.

Structure#

flowchart TB
    G["APG Canonical Governance"]

    G --> C["Codex Adapter"]
    G --> CL["Claude Adapter"]
    G --> GM["Gemini Adapter"]
    G --> CP["Copilot Adapter"]

    C --> A["AGENTS.md"]
    CL --> CM["CLAUDE.md"]
    GM --> GMM["GEMINI.md"]
    CP --> CI["copilot-instructions.md"]

    classDef governance fill:#123d27,stroke:#38c976,stroke-width:2px,color:#ffffff;
    classDef adapter fill:#16231b,stroke:#5d876b,stroke-width:1.5px,color:#ffffff;
    classDef file fill:#0b100d,stroke:#385243,stroke-width:1px,color:#dce8df;

    class G governance;
    class C,CL,GM,CP adapter;
    class A,CM,GMM,CI file;

The framework can distinguish:

flowchart TB
    G["APG Canonical Governance"]

    G --> C["Codex Adapter"]
    G --> CL["Claude Adapter"]
    G --> GM["Gemini Adapter"]
    G --> CP["Copilot Adapter"]

    C --> A["AGENTS.md"]
    CL --> CM["CLAUDE.md"]
    GM --> GMM["GEMINI.md"]
    CP --> CI["copilot-instructions.md"]

    classDef governance fill:#123d27,stroke:#38c976,stroke-width:2px,color:#ffffff;
    classDef adapter fill:#16231b,stroke:#5d876b,stroke-width:1.5px,color:#ffffff;
    classDef file fill:#0b100d,stroke:#385243,stroke-width:1px,color:#dce8df;

    class G governance;
    class C,CL,GM,CP adapter;
    class A,CM,GMM,CI file;

1.9 Example — Documentation, Research, and Knowledge Work#

A non-code repository can also use APG.

Example#

flowchart TB
    G["APG Canonical Governance"]

    G --> C["Codex Adapter"]
    G --> CL["Claude Adapter"]
    G --> GM["Gemini Adapter"]
    G --> CP["Copilot Adapter"]

    C --> A["AGENTS.md"]
    CL --> CM["CLAUDE.md"]
    GM --> GMM["GEMINI.md"]
    CP --> CI["copilot-instructions.md"]

    classDef governance fill:#123d27,stroke:#38c976,stroke-width:2px,color:#ffffff;
    classDef adapter fill:#16231b,stroke:#5d876b,stroke-width:1.5px,color:#ffffff;
    classDef file fill:#0b100d,stroke:#385243,stroke-width:1px,color:#dce8df;

    class G governance;
    class C,CL,GM,CP adapter;
    class A,CM,GMM,CI file;

Possible governance:

flowchart TB
    G["APG Canonical Governance"]

    G --> C["Codex Adapter"]
    G --> CL["Claude Adapter"]
    G --> GM["Gemini Adapter"]
    G --> CP["Copilot Adapter"]

    C --> A["AGENTS.md"]
    CL --> CM["CLAUDE.md"]
    GM --> GMM["GEMINI.md"]
    CP --> CI["copilot-instructions.md"]

    classDef governance fill:#123d27,stroke:#38c976,stroke-width:2px,color:#ffffff;
    classDef adapter fill:#16231b,stroke:#5d876b,stroke-width:1.5px,color:#ffffff;
    classDef file fill:#0b100d,stroke:#385243,stroke-width:1px,color:#dce8df;

    class G governance;
    class C,CL,GM,CP adapter;
    class A,CM,GMM,CI file;

Again, no software code is required for APG to be useful.

1.10 What a New User Actually Does#

A first-time user should not copy the full APG reference repository into a consuming project.

Install only the APG core that is needed and declare existing authoritative project sources through the manifest.

Minimal Core#

flowchart TB
    G["APG Canonical Governance"]

    G --> C["Codex Adapter"]
    G --> CL["Claude Adapter"]
    G --> GM["Gemini Adapter"]
    G --> CP["Copilot Adapter"]

    C --> A["AGENTS.md"]
    CL --> CM["CLAUDE.md"]
    GM --> GMM["GEMINI.md"]
    CP --> CI["copilot-instructions.md"]

    classDef governance fill:#123d27,stroke:#38c976,stroke-width:2px,color:#ffffff;
    classDef adapter fill:#16231b,stroke:#5d876b,stroke-width:1.5px,color:#ffffff;
    classDef file fill:#0b100d,stroke:#385243,stroke-width:1px,color:#dce8df;

    class G governance;
    class C,CL,GM,CP adapter;
    class A,CM,GMM,CI file;

PROJECT.md is optional. The manifest should reference existing authoritative project-native sources.

AGENTS.md#

This file is the entry point and router into governance, the manifest, scoped instructions, and relevant authoritative sources.

Optional Extensions: Workflows, context helpers, roles, templates, additional policies, and profiles are added only when needed.

1.11 The Same Framework Across Different Professions#

The following table shows how APG concepts translate across domains.

The framework stays the same.

The domain content changes.

1.12 When APG Is Useful — and When It Is Not#

APG is useful when#

• multiple people or AI agents work on the same project;
• the project continues over weeks or months;
• rules must survive beyond chat history;
• local areas need different instructions;
• actions have approval or safety boundaries;
• work must be validated;
• knowledge transfer matters;
• different AI tools may be used over time.

APG may be unnecessary when#

• the task is disposable;
• one person is doing a one-off experiment;
• there are no meaningful project rules;
• there is no repeated workflow;
• nothing needs to be handed over or maintained.

APG should create clarity, not ceremony.

2. Problem Statement#

AI agents can generate code, infrastructure, documents, analysis, websites, data pipelines, and operational changes. However, generation alone does not solve project governance.

Common failure modes include:

• Important project knowledge exists only in chat history.
• One large instruction file mixes unrelated concerns.
• Rules for one directory accidentally affect another.
• Security and change-control requirements are treated as optional prompt text.
• An agent claims validation that was never performed.
• A new model or tool requires rewriting the project's operating instructions.
• Different agents receive different versions of the project's rules.
• Repository structure is understandable to humans but not explicitly navigable by agents.
• Temporary task instructions silently override durable project constraints.
• Context windows are polluted by loading every project document for every task.
• A project becomes dependent on a specific AI vendor's configuration format.

APG addresses these problems by defining an explicit hierarchy and separation of concerns.

3. Goals#

APG v1.0 aims to provide:

1. A repository-native project contract.
2. Vendor-neutral governance.
3. Hierarchical and scoped instructions.
4. Explicit rule precedence.
5. Separation of policy, workflow, context, role, and task.
6. Minimal context loading.
7. Evidence-based validation and reporting.
8. Explicit human approval boundaries.
9. A structure usable by software, infrastructure, data, operations, documentation, HR, research, and other project types.
10. Compatibility layers for AI tools without making those tools the source of truth.
11. A minimal bootstrap and validation mechanism.
12. A structure that can be extended without changing the core model.

4. Non-Goals#

APG v1.0 is intentionally not:

• an autonomous agent framework;
• a multi-agent orchestrator;
• an MCP implementation;
• a vector database;
• a memory server;
• a prompt marketplace;
• a collection of personas;
• a replacement for Git;
• a replacement for CI/CD;
• a replacement for IAM or secrets management;
• a replacement for organizational security policy;
• a replacement for change management;
• a model-specific configuration repository;
• a requirement that every project use the same workflow.

The framework governs how project knowledge and operating rules are represented. Execution remains the responsibility of the selected human and/or AI tooling.

5. Design Principles#

5.1 Project over tool#

The repository is the durable source of project truth.

AI tools are consumers of project governance, not owners of it.

5.2 Governance over prompt accumulation#

Durable rules belong in governed project files, not in long-lived prompt fragments or chat history.

5.3 Separation of concerns#

The framework distinguishes:

flowchart TB
    G["APG Canonical Governance"]

    G --> C["Codex Adapter"]
    G --> CL["Claude Adapter"]
    G --> GM["Gemini Adapter"]
    G --> CP["Copilot Adapter"]

    C --> A["AGENTS.md"]
    CL --> CM["CLAUDE.md"]
    GM --> GMM["GEMINI.md"]
    CP --> CI["copilot-instructions.md"]

    classDef governance fill:#123d27,stroke:#38c976,stroke-width:2px,color:#ffffff;
    classDef adapter fill:#16231b,stroke:#5d876b,stroke-width:1.5px,color:#ffffff;
    classDef file fill:#0b100d,stroke:#385243,stroke-width:1px,color:#dce8df;

    class G governance;
    class C,CL,GM,CP adapter;
    class A,CM,GMM,CI file;

Each category answers a different question:

5.4 Scope should follow the repository tree#

Instructions should become more specific as work moves deeper into a project subtree.

5.5 Child rules may specialize, not silently weaken#

A local rule may make a parent rule more specific or more restrictive.

A local rule must not silently bypass security, approval, compliance, or other protected parent constraints.

5.6 Load only relevant context#

Agents should not load the entire governance repository for every task.

Context should be resolved from scope and task requirements.

5.7 Evidence over assertion#

A result is not validated because an agent says it is valid.

Validation requires evidence.

5.8 Explicit authority#

Actions such as deployment, deletion, production changes, secrets operations, financial actions, publishing, or other high-impact actions should have explicit authority boundaries.

5.9 Plain-text portability#

The core should remain readable without proprietary software.

Markdown and small machine-readable manifests are preferred.

5.10 Adapters must remain thin#

Tool-specific files should route a tool into canonical project governance.

They should not become independent copies of the project's rules.

6. Prior Art and Design Lineage#

APG does not claim to invent repository instructions or hierarchical AI context.

Its contribution is the composition of these ideas into a vendor-neutral project-governance architecture.

Existing concepts used as prior art#

OpenAI Codex — AGENTS.md

Codex supports repository instruction discovery using AGENTS.md, including instruction resolution through a project hierarchy.

Source:

• OpenAI Developers — Custom instructions with AGENTS.md
  https://developers.openai.com/codex/agent-configuration/agents-md
• OpenAI Developers — Advanced Configuration
  https://developers.openai.com/codex/config-advanced

Anthropic Claude Code — CLAUDE.md and scoped rules

Claude Code supports persistent project instructions, recursive project memory, nested CLAUDE.md files, imports, and path-scoped rule organization.

Source:

• Anthropic — How Claude remembers your project
  https://docs.anthropic.com/en/docs/claude-code/memory

GitHub Copilot — repository and path-specific instructions

GitHub Copilot supports repository-wide instructions and path-specific instructions.

Source:

• GitHub Docs — Adding repository custom instructions
  https://docs.github.com/copilot/customizing-copilot/adding-custom-instructions-for-github-copilot
• GitHub Docs — Adding custom instructions for GitHub Copilot CLI
  https://docs.github.com/en/copilot/how-tos/copilot-cli/customize-copilot/add-custom-instructions

Gemini CLI — GEMINI.md and hierarchical context

Gemini CLI supports project context files, hierarchical context loading, imports, and on-demand agent skills.

Source:

• Gemini CLI — Provide context with GEMINI.md files
  https://geminicli.com/docs/cli/gemini-md/
• Gemini CLI — Agent Skills
  https://geminicli.com/docs/cli/skills/
• Gemini CLI — Memory Import Processor
  https://geminicli.com/docs/reference/memport/

APG-specific synthesis#

The following architecture is an APG design decision rather than a vendor standard:

flowchart TB
    G["APG Canonical Governance"]

    G --> C["Codex Adapter"]
    G --> CL["Claude Adapter"]
    G --> GM["Gemini Adapter"]
    G --> CP["Copilot Adapter"]

    C --> A["AGENTS.md"]
    CL --> CM["CLAUDE.md"]
    GM --> GMM["GEMINI.md"]
    CP --> CI["copilot-instructions.md"]

    classDef governance fill:#123d27,stroke:#38c976,stroke-width:2px,color:#ffffff;
    classDef adapter fill:#16231b,stroke:#5d876b,stroke-width:1.5px,color:#ffffff;
    classDef file fill:#0b100d,stroke:#385243,stroke-width:1px,color:#dce8df;

    class G governance;
    class C,CL,GM,CP adapter;
    class A,CM,GMM,CI file;

7. Repository Structure#

The v1.0 public reference repository is:

flowchart TB
    G["APG Canonical Governance"]

    G --> C["Codex Adapter"]
    G --> CL["Claude Adapter"]
    G --> GM["Gemini Adapter"]
    G --> CP["Copilot Adapter"]

    C --> A["AGENTS.md"]
    CL --> CM["CLAUDE.md"]
    GM --> GMM["GEMINI.md"]
    CP --> CI["copilot-instructions.md"]

    classDef governance fill:#123d27,stroke:#38c976,stroke-width:2px,color:#ffffff;
    classDef adapter fill:#16231b,stroke:#5d876b,stroke-width:1.5px,color:#ffffff;
    classDef file fill:#0b100d,stroke:#385243,stroke-width:1px,color:#dce8df;

    class G governance;
    class C,CL,GM,CP adapter;
    class A,CM,GMM,CI file;

8. Root File Contracts#

8.1 README.md#

Purpose#

Public entry point for humans.

Contains#

• what APG is;
• problem statement;
• quick start;
• small architecture diagram;
• example repository;
• supported concepts;
• current specification version;
• links to detailed documentation;
• contribution information.

Must not contain#

The complete governance specification.

The README should remain consumable in a few minutes.

8.2 AGENTS.md#

Purpose#

Portable AI-agent entry point and router.

Important design rule#

AGENTS.md is not the canonical database of all project rules.

It tells an AI agent how to resolve the project contract.

Recommended responsibilities#

1. Identify the repository governance files.
2. Tell the agent to inspect project evidence before modifying anything.
3. Describe scoped instruction inheritance.
4. Point to the policy and workflow resolver.
5. Define minimum validation/reporting expectations.
6. Tell the agent how to react to conflicts or missing authority.

Recommended maximum size#

Prefer a concise routing document rather than a large prompt.

A typical root file should be approximately 50–150 lines, depending on project complexity.

8.3 GOVERNANCE.md#

Purpose#

The repository's constitutional contract.

This is the highest repository-level normative document in APG.

Contains#

• governance scope;
• authority model;
• instruction precedence;
• protected constraints;
• approval requirements;
• security boundaries;
• change rules;
• validation obligations;
• stop/block conditions;
• exception process;
• rule ownership;
• governance modification rules.

Example concerns#

flowchart TB
    G["APG Canonical Governance"]

    G --> C["Codex Adapter"]
    G --> CL["Claude Adapter"]
    G --> GM["Gemini Adapter"]
    G --> CP["Copilot Adapter"]

    C --> A["AGENTS.md"]
    CL --> CM["CLAUDE.md"]
    GM --> GMM["GEMINI.md"]
    CP --> CI["copilot-instructions.md"]

    classDef governance fill:#123d27,stroke:#38c976,stroke-width:2px,color:#ffffff;
    classDef adapter fill:#16231b,stroke:#5d876b,stroke-width:1.5px,color:#ffffff;
    classDef file fill:#0b100d,stroke:#385243,stroke-width:1px,color:#dce8df;

    class G governance;
    class C,CL,GM,CP adapter;
    class A,CM,GMM,CI file;

8.4 PROJECT.md#

Purpose#

PROJECT.md is an optional project source, not a universal APG requirement.

If authoritative project-native sources already exist, the manifest should reference them.

8.5 CHANGELOG.md#

Tracks framework releases and specification changes.

Recommended format:

flowchart TB
    G["APG Canonical Governance"]

    G --> C["Codex Adapter"]
    G --> CL["Claude Adapter"]
    G --> GM["Gemini Adapter"]
    G --> CP["Copilot Adapter"]

    C --> A["AGENTS.md"]
    CL --> CM["CLAUDE.md"]
    GM --> GMM["GEMINI.md"]
    CP --> CI["copilot-instructions.md"]

    classDef governance fill:#123d27,stroke:#38c976,stroke-width:2px,color:#ffffff;
    classDef adapter fill:#16231b,stroke:#5d876b,stroke-width:1.5px,color:#ffffff;
    classDef file fill:#0b100d,stroke:#385243,stroke-width:1px,color:#dce8df;

    class G governance;
    class C,CL,GM,CP adapter;
    class A,CM,GMM,CI file;

8.6 CONTRIBUTING.md#

Defines how the public community contributes.

Should cover:

• issue-first vs direct PR policy;
• proposal process;
• tests/validation required;
• documentation expectations;
• backward compatibility expectations;
• review rules;
• specification change process.

8.7 SECURITY.md#

Defines responsible security reporting.

It should not contain secrets, operational credentials, or sensitive implementation data.

8.8 LICENSE#

The project should ship with an explicit open-source license before public release.

License selection should be a deliberate maintainer decision.

9. .governance/ — Canonical Governance Layer#

.governance/ contains the reusable and project-specific governance components used by the root contract.

The directory is intentionally vendor-neutral.

9.1 .governance/README.md#

Explains the internal structure and authoring rules for governance components.

This is primarily for contributors and maintainers.

9.2 .governance/manifest.yaml#

Machine-readable governance manifest.

Purpose#

Provide a small stable index that tools can validate without parsing every Markdown document.

v1.0 manifest shape#

spec_version: "1.0"

governance:
  root: "GOVERNANCE.md"
  entry_adapter: "AGENTS.md"

project_sources:
  overview:
    - "README.md"

resolution:
  instruction_file: "AGENTS.md"
  inheritance: "root-to-leaf"
  source_strategy: "declared-authoritative-sources"
  context_strategy: "task-relevant-only"
  local_rules_may:
    - specialize
    - restrict
  local_rules_may_not:
    - silently_weaken_parent_policy
    - bypass_required_approval
    - bypass_security_controls
    - replace_authoritative_sources_without_governance_change

core:
  authority_policy: ".governance/policies/authority.md"
  validation_policy: ".governance/policies/validation.md"

extensions:
  policies: ".governance/policies"
  workflows: ".governance/workflows"
  context: ".governance/context"
  roles: ".governance/roles"
  templates: ".governance/templates"

validation:
  require_evidence: true
  allow_unvalidated_claims: false

The manifest must remain small.

It is an index, not a replacement for Markdown governance.

10. Policies#

Policies answer:

What constraints apply regardless of how the task is implemented?

10.1 policies/authority.md#

Defines authority boundaries.

Examples:

• read-only operations;
• write operations;
• destructive actions;
• deployment;
• external publication;
• financial actions;
• production operations;
• approval delegation.

10.2 policies/change-control.md#

Defines change classes and change requirements.

Possible categories:

flowchart TB
    G["APG Canonical Governance"]

    G --> C["Codex Adapter"]
    G --> CL["Claude Adapter"]
    G --> GM["Gemini Adapter"]
    G --> CP["Copilot Adapter"]

    C --> A["AGENTS.md"]
    CL --> CM["CLAUDE.md"]
    GM --> GMM["GEMINI.md"]
    CP --> CI["copilot-instructions.md"]

    classDef governance fill:#123d27,stroke:#38c976,stroke-width:2px,color:#ffffff;
    classDef adapter fill:#16231b,stroke:#5d876b,stroke-width:1.5px,color:#ffffff;
    classDef file fill:#0b100d,stroke:#385243,stroke-width:1px,color:#dce8df;

    class G governance;
    class C,CL,GM,CP adapter;
    class A,CM,GMM,CI file;

The framework does not require every domain to use all categories.

10.3 policies/security.md#

Defines security constraints.

Examples:

• never commit secrets;
• do not expose confidential data;
• use least privilege;
• preserve security controls;
• do not disable protections merely to pass validation;
• explicitly identify unverified security assumptions.

10.4 policies/validation.md#

Defines what constitutes acceptable evidence.

Examples:

• test output;
• lint result;
• build result;
• diff inspection;
• API response;
• health check;
• reviewer approval;
• reconciliation against desired state.

10.5 policies/documentation.md#

Defines what must be documented after material changes.

Examples:

• architecture impact;
• operational impact;
• rollback;
• known limitation;
• decision rationale;
• handover information.

11. Workflows#

Workflows answer:

How should this type of work normally proceed?

Policies constrain workflows.

Workflows do not override governance.

11.1 workflows/default.md#

Generic lifecycle for work without a specialized workflow.

Recommended sequence:

flowchart TB
    G["APG Canonical Governance"]

    G --> C["Codex Adapter"]
    G --> CL["Claude Adapter"]
    G --> GM["Gemini Adapter"]
    G --> CP["Copilot Adapter"]

    C --> A["AGENTS.md"]
    CL --> CM["CLAUDE.md"]
    GM --> GMM["GEMINI.md"]
    CP --> CI["copilot-instructions.md"]

    classDef governance fill:#123d27,stroke:#38c976,stroke-width:2px,color:#ffffff;
    classDef adapter fill:#16231b,stroke:#5d876b,stroke-width:1.5px,color:#ffffff;
    classDef file fill:#0b100d,stroke:#385243,stroke-width:1px,color:#dce8df;

    class G governance;
    class C,CL,GM,CP adapter;
    class A,CM,GMM,CI file;

11.2 workflows/implementation.md#

Used for creating or changing project artifacts.

Typical stages:

flowchart TB
    G["APG Canonical Governance"]

    G --> C["Codex Adapter"]
    G --> CL["Claude Adapter"]
    G --> GM["Gemini Adapter"]
    G --> CP["Copilot Adapter"]

    C --> A["AGENTS.md"]
    CL --> CM["CLAUDE.md"]
    GM --> GMM["GEMINI.md"]
    CP --> CI["copilot-instructions.md"]

    classDef governance fill:#123d27,stroke:#38c976,stroke-width:2px,color:#ffffff;
    classDef adapter fill:#16231b,stroke:#5d876b,stroke-width:1.5px,color:#ffffff;
    classDef file fill:#0b100d,stroke:#385243,stroke-width:1px,color:#dce8df;

    class G governance;
    class C,CL,GM,CP adapter;
    class A,CM,GMM,CI file;

11.3 workflows/review.md#

Used when evaluating existing work.

Typical stages:

flowchart TB
    G["APG Canonical Governance"]

    G --> C["Codex Adapter"]
    G --> CL["Claude Adapter"]
    G --> GM["Gemini Adapter"]
    G --> CP["Copilot Adapter"]

    C --> A["AGENTS.md"]
    CL --> CM["CLAUDE.md"]
    GM --> GMM["GEMINI.md"]
    CP --> CI["copilot-instructions.md"]

    classDef governance fill:#123d27,stroke:#38c976,stroke-width:2px,color:#ffffff;
    classDef adapter fill:#16231b,stroke:#5d876b,stroke-width:1.5px,color:#ffffff;
    classDef file fill:#0b100d,stroke:#385243,stroke-width:1px,color:#dce8df;

    class G governance;
    class C,CL,GM,CP adapter;
    class A,CM,GMM,CI file;

A review should not silently become an implementation task.

11.4 workflows/handover.md#

Defines completion information needed when work changes ownership.

Examples:

• what changed;
• why;
• validation performed;
• validation not performed;
• operational dependencies;
• rollback/recovery information;
• remaining risks;
• next owner/action.

12. Context#

Context answers:

What facts does the agent need to know?

Context is descriptive, not normative.

This distinction is critical.

12.1 context/architecture.md#

High-level architecture and component relationships.

Should focus on facts required to understand the system.

12.2 context/conventions.md#

Project conventions.

Examples:

• naming;
• directory conventions;
• coding conventions;
• documentation conventions;
• commit conventions;
• environment naming.

If a convention is mandatory for security or governance reasons, its normative requirement belongs in policy and may be referenced here.

12.3 context/glossary.md#

Defines project-specific terminology.

Useful for domains where acronyms and internal terms would otherwise be ambiguous.

12.4 context/current-state.md#

Optional volatile context.

Examples:

• active migration;
• current release;
• temporary constraint;
• known incident;
• currently active environment.

This file should include a visible Last Updated value.

Agents should treat stale current-state information cautiously.

13. Roles#

Roles answer:

What responsibility or review perspective applies to this task?

Roles are not fictional personalities.

A role defines responsibilities, boundaries, and expected outputs.

13.1 roles/contributor.md#

Typical responsibilities:

• inspect existing work;
• make bounded changes;
• follow applicable policies;
• validate changes;
• report evidence.

13.2 roles/reviewer.md#

Typical responsibilities:

• remain independent from implementation assumptions;
• identify correctness, safety, maintainability, and governance issues;
• distinguish verified findings from suspicions;
• avoid modifying artifacts unless review scope explicitly includes remediation.

13.3 roles/operator.md#

Typical responsibilities:

• prioritize system state and operational safety;
• use explicit scope;
• honor approval boundaries;
• prefer reversible operations;
• validate post-change state.

Projects may define their own roles.

Examples:

flowchart TB
    G["APG Canonical Governance"]

    G --> C["Codex Adapter"]
    G --> CL["Claude Adapter"]
    G --> GM["Gemini Adapter"]
    G --> CP["Copilot Adapter"]

    C --> A["AGENTS.md"]
    CL --> CM["CLAUDE.md"]
    GM --> GMM["GEMINI.md"]
    CP --> CI["copilot-instructions.md"]

    classDef governance fill:#123d27,stroke:#38c976,stroke-width:2px,color:#ffffff;
    classDef adapter fill:#16231b,stroke:#5d876b,stroke-width:1.5px,color:#ffffff;
    classDef file fill:#0b100d,stroke:#385243,stroke-width:1px,color:#dce8df;

    class G governance;
    class C,CL,GM,CP adapter;
    class A,CM,GMM,CI file;

14. Templates#

Templates standardize recurring artifacts without forcing a domain-specific workflow.

14.1 templates/task.md#

Suggested fields:

flowchart TB
    G["APG Canonical Governance"]

    G --> C["Codex Adapter"]
    G --> CL["Claude Adapter"]
    G --> GM["Gemini Adapter"]
    G --> CP["Copilot Adapter"]

    C --> A["AGENTS.md"]
    CL --> CM["CLAUDE.md"]
    GM --> GMM["GEMINI.md"]
    CP --> CI["copilot-instructions.md"]

    classDef governance fill:#123d27,stroke:#38c976,stroke-width:2px,color:#ffffff;
    classDef adapter fill:#16231b,stroke:#5d876b,stroke-width:1.5px,color:#ffffff;
    classDef file fill:#0b100d,stroke:#385243,stroke-width:1px,color:#dce8df;

    class G governance;
    class C,CL,GM,CP adapter;
    class A,CM,GMM,CI file;

14.2 templates/decision.md#

Suggested fields:

flowchart TB
    G["APG Canonical Governance"]

    G --> C["Codex Adapter"]
    G --> CL["Claude Adapter"]
    G --> GM["Gemini Adapter"]
    G --> CP["Copilot Adapter"]

    C --> A["AGENTS.md"]
    CL --> CM["CLAUDE.md"]
    GM --> GMM["GEMINI.md"]
    CP --> CI["copilot-instructions.md"]

    classDef governance fill:#123d27,stroke:#38c976,stroke-width:2px,color:#ffffff;
    classDef adapter fill:#16231b,stroke:#5d876b,stroke-width:1.5px,color:#ffffff;
    classDef file fill:#0b100d,stroke:#385243,stroke-width:1px,color:#dce8df;

    class G governance;
    class C,CL,GM,CP adapter;
    class A,CM,GMM,CI file;

This can later evolve into ADR compatibility if desired.

14.3 templates/report.md#

Suggested fields:

flowchart TB
    G["APG Canonical Governance"]

    G --> C["Codex Adapter"]
    G --> CL["Claude Adapter"]
    G --> GM["Gemini Adapter"]
    G --> CP["Copilot Adapter"]

    C --> A["AGENTS.md"]
    CL --> CM["CLAUDE.md"]
    GM --> GMM["GEMINI.md"]
    CP --> CI["copilot-instructions.md"]

    classDef governance fill:#123d27,stroke:#38c976,stroke-width:2px,color:#ffffff;
    classDef adapter fill:#16231b,stroke:#5d876b,stroke-width:1.5px,color:#ffffff;
    classDef file fill:#0b100d,stroke:#385243,stroke-width:1px,color:#dce8df;

    class G governance;
    class C,CL,GM,CP adapter;
    class A,CM,GMM,CI file;

14.4 templates/handover.md#

Suggested fields:

flowchart TB
    G["APG Canonical Governance"]

    G --> C["Codex Adapter"]
    G --> CL["Claude Adapter"]
    G --> GM["Gemini Adapter"]
    G --> CP["Copilot Adapter"]

    C --> A["AGENTS.md"]
    CL --> CM["CLAUDE.md"]
    GM --> GMM["GEMINI.md"]
    CP --> CI["copilot-instructions.md"]

    classDef governance fill:#123d27,stroke:#38c976,stroke-width:2px,color:#ffffff;
    classDef adapter fill:#16231b,stroke:#5d876b,stroke-width:1.5px,color:#ffffff;
    classDef file fill:#0b100d,stroke:#385243,stroke-width:1px,color:#dce8df;

    class G governance;
    class C,CL,GM,CP adapter;
    class A,CM,GMM,CI file;

15. Hierarchical AGENTS.md#

Hierarchical instruction resolution is central to APG.

Example project:

flowchart TB
    G["APG Canonical Governance"]

    G --> C["Codex Adapter"]
    G --> CL["Claude Adapter"]
    G --> GM["Gemini Adapter"]
    G --> CP["Copilot Adapter"]

    C --> A["AGENTS.md"]
    CL --> CM["CLAUDE.md"]
    GM --> GMM["GEMINI.md"]
    CP --> CI["copilot-instructions.md"]

    classDef governance fill:#123d27,stroke:#38c976,stroke-width:2px,color:#ffffff;
    classDef adapter fill:#16231b,stroke:#5d876b,stroke-width:1.5px,color:#ffffff;
    classDef file fill:#0b100d,stroke:#385243,stroke-width:1px,color:#dce8df;

    class G governance;
    class C,CL,GM,CP adapter;
    class A,CM,GMM,CI file;

For work inside:

flowchart TB
    G["APG Canonical Governance"]

    G --> C["Codex Adapter"]
    G --> CL["Claude Adapter"]
    G --> GM["Gemini Adapter"]
    G --> CP["Copilot Adapter"]

    C --> A["AGENTS.md"]
    CL --> CM["CLAUDE.md"]
    GM --> GMM["GEMINI.md"]
    CP --> CI["copilot-instructions.md"]

    classDef governance fill:#123d27,stroke:#38c976,stroke-width:2px,color:#ffffff;
    classDef adapter fill:#16231b,stroke:#5d876b,stroke-width:1.5px,color:#ffffff;
    classDef file fill:#0b100d,stroke:#385243,stroke-width:1px,color:#dce8df;

    class G governance;
    class C,CL,GM,CP adapter;
    class A,CM,GMM,CI file;

the effective instruction chain is conceptually:

flowchart TB
    G["APG Canonical Governance"]

    G --> C["Codex Adapter"]
    G --> CL["Claude Adapter"]
    G --> GM["Gemini Adapter"]
    G --> CP["Copilot Adapter"]

    C --> A["AGENTS.md"]
    CL --> CM["CLAUDE.md"]
    GM --> GMM["GEMINI.md"]
    CP --> CI["copilot-instructions.md"]

    classDef governance fill:#123d27,stroke:#38c976,stroke-width:2px,color:#ffffff;
    classDef adapter fill:#16231b,stroke:#5d876b,stroke-width:1.5px,color:#ffffff;
    classDef file fill:#0b100d,stroke:#385243,stroke-width:1px,color:#dce8df;

    class G governance;
    class C,CL,GM,CP adapter;
    class A,CM,GMM,CI file;

A child AGENTS.md should contain only rules and routing information specific to its scope.

It should not duplicate the root governance document.

16. Suggested Scoped AGENTS.md Contract#

APG may use optional YAML front matter to make scope explicit while remaining readable as normal Markdown.

Example:

---
apg:
  spec_version: "1.0"
  scope: "./"
  inherits: true
  policies:
    - "/.governance/policies/security.md"
    - "/.governance/policies/validation.md"
  workflow:
    - "/.governance/workflows/implementation.md"
---

# Infrastructure Instructions

## Scope

These instructions apply to this directory and its descendants.

## Local Requirements

- Inspect existing infrastructure definitions before creating new ones.
- Prefer existing modules, roles, and automation.
- Do not perform production changes without applicable authority.
- Validate syntax before execution where supported.

## Local Context

See `architecture.md` in this subtree when the task affects deployment topology.

Front matter is an APG convention.

Native AI tools are not required to implement APG parsing for the text to remain useful.

17. Instruction Precedence#

APG distinguishes loading order from authority precedence.

A tool may load files differently, but the project governance model must explicitly define which instruction wins.

Recommended conceptual precedence:

flowchart TB
    G["APG Canonical Governance"]

    G --> C["Codex Adapter"]
    G --> CL["Claude Adapter"]
    G --> GM["Gemini Adapter"]
    G --> CP["Copilot Adapter"]

    C --> A["AGENTS.md"]
    CL --> CM["CLAUDE.md"]
    GM --> GMM["GEMINI.md"]
    CP --> CI["copilot-instructions.md"]

    classDef governance fill:#123d27,stroke:#38c976,stroke-width:2px,color:#ffffff;
    classDef adapter fill:#16231b,stroke:#5d876b,stroke-width:1.5px,color:#ffffff;
    classDef file fill:#0b100d,stroke:#385243,stroke-width:1px,color:#dce8df;

    class G governance;
    class C,CL,GM,CP adapter;
    class A,CM,GMM,CI file;

Important rule:

More specific does not automatically mean more authoritative.

Example:

A local file may say:

flowchart TB
    G["APG Canonical Governance"]

    G --> C["Codex Adapter"]
    G --> CL["Claude Adapter"]
    G --> GM["Gemini Adapter"]
    G --> CP["Copilot Adapter"]

    C --> A["AGENTS.md"]
    CL --> CM["CLAUDE.md"]
    GM --> GMM["GEMINI.md"]
    CP --> CI["copilot-instructions.md"]

    classDef governance fill:#123d27,stroke:#38c976,stroke-width:2px,color:#ffffff;
    classDef adapter fill:#16231b,stroke:#5d876b,stroke-width:1.5px,color:#ffffff;
    classDef file fill:#0b100d,stroke:#385243,stroke-width:1px,color:#dce8df;

    class G governance;
    class C,CL,GM,CP adapter;
    class A,CM,GMM,CI file;

If root governance requires human approval for production deployment, the local instruction cannot remove that approval requirement.

18. Rule Conflict Resolution#

When two instructions conflict:

Step 1 — Determine scope#

Check whether both instructions actually apply to the current task.

Step 2 — Determine authority#

Use governance precedence, not file proximity alone.

Step 3 — Determine whether specialization is allowed#

A child may specialize a parent rule where the parent permits specialization.

Step 4 — Protect non-weakenable constraints#

Security, approval, compliance, and destructive-action constraints should not be silently weakened.

Step 5 — Block if ambiguity changes risk#

If resolving the ambiguity would materially change authority or risk, the task should stop at the decision boundary rather than guessing.

19. Context Resolution#

APG uses progressive context resolution.

The agent should not consume all project documents by default.

Conceptual resolver:

flowchart TB
    G["APG Canonical Governance"]

    G --> C["Codex Adapter"]
    G --> CL["Claude Adapter"]
    G --> GM["Gemini Adapter"]
    G --> CP["Copilot Adapter"]

    C --> A["AGENTS.md"]
    CL --> CM["CLAUDE.md"]
    GM --> GMM["GEMINI.md"]
    CP --> CI["copilot-instructions.md"]

    classDef governance fill:#123d27,stroke:#38c976,stroke-width:2px,color:#ffffff;
    classDef adapter fill:#16231b,stroke:#5d876b,stroke-width:1.5px,color:#ffffff;
    classDef file fill:#0b100d,stroke:#385243,stroke-width:1px,color:#dce8df;

    class G governance;
    class C,CL,GM,CP adapter;
    class A,CM,GMM,CI file;

This is intentionally compatible with the direction of current agent tools that support scoped instructions or on-demand capabilities, while APG's exact resolver is its own framework-level abstraction.

20. Evidence and Validation Model#

APG separates:

flowchart TB
    G["APG Canonical Governance"]

    G --> C["Codex Adapter"]
    G --> CL["Claude Adapter"]
    G --> GM["Gemini Adapter"]
    G --> CP["Copilot Adapter"]

    C --> A["AGENTS.md"]
    CL --> CM["CLAUDE.md"]
    GM --> GMM["GEMINI.md"]
    CP --> CI["copilot-instructions.md"]

    classDef governance fill:#123d27,stroke:#38c976,stroke-width:2px,color:#ffffff;
    classDef adapter fill:#16231b,stroke:#5d876b,stroke-width:1.5px,color:#ffffff;
    classDef file fill:#0b100d,stroke:#385243,stroke-width:1px,color:#dce8df;

    class G governance;
    class C,CL,GM,CP adapter;
    class A,CM,GMM,CI file;

These are not interchangeable.

Example:

flowchart TB
    G["APG Canonical Governance"]

    G --> C["Codex Adapter"]
    G --> CL["Claude Adapter"]
    G --> GM["Gemini Adapter"]
    G --> CP["Copilot Adapter"]

    C --> A["AGENTS.md"]
    CL --> CM["CLAUDE.md"]
    GM --> GMM["GEMINI.md"]
    CP --> CI["copilot-instructions.md"]

    classDef governance fill:#123d27,stroke:#38c976,stroke-width:2px,color:#ffffff;
    classDef adapter fill:#16231b,stroke:#5d876b,stroke-width:1.5px,color:#ffffff;
    classDef file fill:#0b100d,stroke:#385243,stroke-width:1px,color:#dce8df;

    class G governance;
    class C,CL,GM,CP adapter;
    class A,CM,GMM,CI file;

The agent must not produce:

flowchart TB
    G["APG Canonical Governance"]

    G --> C["Codex Adapter"]
    G --> CL["Claude Adapter"]
    G --> GM["Gemini Adapter"]
    G --> CP["Copilot Adapter"]

    C --> A["AGENTS.md"]
    CL --> CM["CLAUDE.md"]
    GM --> GMM["GEMINI.md"]
    CP --> CI["copilot-instructions.md"]

    classDef governance fill:#123d27,stroke:#38c976,stroke-width:2px,color:#ffffff;
    classDef adapter fill:#16231b,stroke:#5d876b,stroke-width:1.5px,color:#ffffff;
    classDef file fill:#0b100d,stroke:#385243,stroke-width:1px,color:#dce8df;

    class G governance;
    class C,CL,GM,CP adapter;
    class A,CM,GMM,CI file;

when validation was not actually performed.

Recommended reporting vocabulary:

Projects may extend the vocabulary but should not redefine these statuses ambiguously.

21. Human Authority Model#

A core APG concept is an explicit decision boundary between analysis and action.

Example classes:

flowchart TB
    G["APG Canonical Governance"]

    G --> C["Codex Adapter"]
    G --> CL["Claude Adapter"]
    G --> GM["Gemini Adapter"]
    G --> CP["Copilot Adapter"]

    C --> A["AGENTS.md"]
    CL --> CM["CLAUDE.md"]
    GM --> GMM["GEMINI.md"]
    CP --> CI["copilot-instructions.md"]

    classDef governance fill:#123d27,stroke:#38c976,stroke-width:2px,color:#ffffff;
    classDef adapter fill:#16231b,stroke:#5d876b,stroke-width:1.5px,color:#ffffff;
    classDef file fill:#0b100d,stroke:#385243,stroke-width:1px,color:#dce8df;

    class G governance;
    class C,CL,GM,CP adapter;
    class A,CM,GMM,CI file;

A project may map these to human roles.

Example:

authority:
  observe:
    default: allowed
  propose:
    default: allowed
  modify:
    default: task-scoped
  deploy:
    default: approval-required
  delete:
    default: approval-required
  publish:
    default: approval-required

This is a governance model, not an access-control system.

Actual enforcement remains the responsibility of the runtime environment, IAM, CI/CD, operating system, and connected tools.

22. Vendor Adapter Model#

The project core is vendor-neutral.

Adapters translate or route the project contract into the conventions used by a specific tool.

flowchart TB
    G["APG Canonical Governance"]

    G --> C["Codex Adapter"]
    G --> CL["Claude Adapter"]
    G --> GM["Gemini Adapter"]
    G --> CP["Copilot Adapter"]

    C --> A["AGENTS.md"]
    CL --> CM["CLAUDE.md"]
    GM --> GMM["GEMINI.md"]
    CP --> CI["copilot-instructions.md"]

    classDef governance fill:#123d27,stroke:#38c976,stroke-width:2px,color:#ffffff;
    classDef adapter fill:#16231b,stroke:#5d876b,stroke-width:1.5px,color:#ffffff;
    classDef file fill:#0b100d,stroke:#385243,stroke-width:1px,color:#dce8df;

    class G governance;
    class C,CL,GM,CP adapter;
    class A,CM,GMM,CI file;

Adapters should:

• point to canonical project documents;
• contain only compatibility-specific guidance;
• avoid copying entire policies;
• clearly identify generated content if generation is introduced later.

Adapters should not:

• redefine project governance;
• weaken project security;
• create independent policy branches;
• become the only place important rules exist.

23. Profiles#

Profiles provide optional domain defaults.

They are not part of the mandatory core.

Initial profiles included in v1.0:

generic/
software/
devops/

Future profiles may include:

data/
security/
research/
documentation/
product/
hr/
legal/
finance/

A profile may add:

• policies;
• workflows;
• roles;
• context templates;
• scoped instruction examples.

A profile must not change the APG core semantics.

24. Examples#

24.1 examples/minimal/#

Shows the smallest useful APG project.

Suggested tree:

minimal/
├── AGENTS.md
├── GOVERNANCE.md
├── PROJECT.md
└── .governance/
    ├── manifest.yaml
    ├── policies/
    │   └── validation.md
    └── workflows/
        └── default.md

24.2 examples/monorepo/#

Demonstrates scoped instructions.

monorepo/
├── AGENTS.md
├── GOVERNANCE.md
├── PROJECT.md
├── frontend/
│   └── AGENTS.md
├── backend/
│   └── AGENTS.md
└── infrastructure/
    ├── AGENTS.md
    └── ansible/
        └── AGENTS.md

24.3 examples/operations/#

Demonstrates stronger authority and change-control boundaries.

Example lifecycle:

Scope
→ Precheck
→ Canary
→ Approval Boundary
→ Apply
→ Validation
→ Report

This workflow is domain-specific and is deliberately not forced on every APG project.

25. Tools#

The framework should remain useful without any executable tooling.

Tools are convenience functions.

25.1 tools/init-project.sh#

Purpose:

Initialize APG structure inside a repository.

Possible future interface:

./tools/init-project.sh \
  --target /path/to/project \
  --profile software

v1.0 requirements:

• never overwrite existing files without explicit intent;
• print planned actions;
• support a dry-run mode;
• copy only the selected minimal profile;
• return non-zero on validation errors.

25.2 tools/validate-project.sh#

Purpose:

Validate the APG structure itself.

Possible checks:

manifest exists
manifest spec version is supported
declared files exist
root governance exists
project definition exists
entrypoint exists
referenced policy files exist
referenced workflow files exist
scoped files do not reference missing documents
required headings exist
no obvious secret patterns exist in governance files

The validator checks structure.

It does not prove that the project's business rules are correct.

26. Documentation Set#

docs/architecture.md#

Deep explanation of components and boundaries.

docs/governance-model.md#

Normative governance semantics.

docs/instruction-resolution.md#

How root and scoped instructions are resolved.

docs/authoring-guide.md#

How maintainers should write good governance documents.

docs/adapter-model.md#

Rules for model/tool integrations.

docs/extension-model.md#

How profiles, roles, workflows, policies, and adapters can be added safely.

docs/prior-art.md#

Detailed lineage and references to existing tools and concepts.

27. Public GitHub Support Files#

.github/ISSUE_TEMPLATE/bug.yml#

For defects in framework behavior, documentation, templates, or tooling.

.github/ISSUE_TEMPLATE/proposal.yml#

For changes to:

• core semantics;
• new profile types;
• new adapters;
• precedence rules;
• governance contracts.

.github/PULL_REQUEST_TEMPLATE.md#

Recommended checklist:

- Scope is clear.
- The change does not duplicate existing governance.
- Core semantics remain vendor-neutral.
- Documentation was updated if behavior changed.
- Examples were updated where applicable.
- Validation was performed.
- Breaking changes are identified.

28. Mermaid — Core Architecture#

flowchart TD
    H[Human / Team] --> T[AI Tool or Agent]
    T --> A[Tool Adapter]
    A --> E[Project Entry Point]

    E --> G[GOVERNANCE.md]
    E --> P[PROJECT.md]
    E --> S[Scoped Instructions]

    G --> R[Governance Resolver]
    P --> R
    S --> R

    R --> POL[Policies]
    R --> WF[Workflow]
    R --> ROLE[Role]
    R --> CTX[Relevant Context]

    POL --> X[Task Execution]
    WF --> X
    ROLE --> X
    CTX --> X

    X --> V[Validation]
    V --> EV[Evidence]
    EV --> REP[Report / Handover]
    REP --> H

Meaning#

The AI tool does not directly define project behavior.

It enters through a compatibility layer, resolves the canonical project contract, performs the task under applicable governance, validates the result, and returns evidence.

29. Mermaid — Governance Precedence#

flowchart TD
    EXT[External Platform / Security Controls]
    ORG[Organization Mandatory Policy]
    GOV[Repository GOVERNANCE.md]
    PP[Protected Project Policies]
    PAR[Parent Scoped Instructions]
    LOC[Nearest Scoped Instructions]
    WF[Applicable Workflow]
    ROLE[Role Guidance]
    TASK[Current Task]
    DEF[Framework Defaults]

    EXT --> ORG
    ORG --> GOV
    GOV --> PP
    PP --> PAR
    PAR --> LOC
    LOC --> WF
    WF --> ROLE
    ROLE --> TASK
    TASK --> DEF

Key rule#

Lower layers may add specificity when allowed, but they do not automatically gain authority to weaken higher-level protected constraints.

30. Mermaid — Hierarchical Instruction Resolution#

flowchart TD
    TASK[Task targets infrastructure/ansible/playbooks]
    ROOT[Root AGENTS.md]
    INFRA[infrastructure/AGENTS.md]
    ANS[ansible/AGENTS.md]
    POL[Applicable Policies]
    WF[Applicable Workflow]
    CTX[Required Context]
    EXEC[Effective Task Context]

    TASK --> ROOT
    ROOT --> INFRA
    INFRA --> ANS
    ANS --> POL
    POL --> WF
    WF --> CTX
    CTX --> EXEC

This represents APG's conceptual resolver.

Exact native loading behavior depends on the selected AI tool.

31. Mermaid — Task Lifecycle#

flowchart LR
    S[Scope] --> I[Inspect]
    I --> C[Resolve Context]
    C --> P[Plan]
    P --> A{Authority available?}

    A -- No --> B[BLOCKED / Proposal Only]
    A -- Yes --> E[Execute]

    E --> V[Validate]
    V --> R{Evidence sufficient?}

    R -- Yes --> PASS[Report Verified Result]
    R -- No --> NV[Report NOT_VALIDATED]

    PASS --> H[Handover / Complete]
    NV --> H
    B --> H

32. Mermaid — Extension Model#

flowchart TD
    CORE[APG Core Semantics]

    CORE --> PROF[Profiles]
    CORE --> ADAPT[Adapters]
    CORE --> PROJ[Project-Specific Governance]

    PROF --> SW[Software]
    PROF --> DO[DevOps]
    PROF --> GEN[Generic]

    ADAPT --> CDX[Codex]
    ADAPT --> CLD[Claude]
    ADAPT --> GEM[Gemini]
    ADAPT --> COP[Copilot]

    PROJ --> LOCAL[Scoped Instructions]
    PROJ --> CONTEXT[Project Context]
    PROJ --> POLICY[Project Policies]
    PROJ --> WORKFLOW[Project Workflows]

Core semantics remain independent of profiles and tool adapters.

33. Mermaid — Information Ownership#

flowchart TB
    Q{What kind of information is this?}

    Q -->|Authority / invariant| GOV[Governance or Policy]
    Q -->|Fact about project| CTX[Context]
    Q -->|Procedure| WF[Workflow]
    Q -->|Responsibility| ROLE[Role]
    Q -->|One current request| TASK[Task]
    Q -->|Tool compatibility| ADAPTER[Adapter]
    Q -->|Proof of result| EVIDENCE[Validation Evidence]

This decision tree prevents the common failure mode of putting everything into one agent instruction file.

34. Minimal APG Adoption#

A project should not be required to copy the entire reference repository.

Minimum practical adoption:

project/
├── AGENTS.md
├── GOVERNANCE.md
├── PROJECT.md
└── .governance/
    ├── manifest.yaml
    ├── policies/
    │   └── validation.md
    └── workflows/
        └── default.md

Additional components are added only when they solve a real project need.

This is a key design principle:

The reference repository may be comprehensive. A consuming project should remain minimal.

35. Full Reference Repository vs Consuming Project#

These are different concepts.

Reference repository#

The public APG repository contains:

• specification;
• documentation;
• profiles;
• examples;
• adapters;
• templates;
• tools;
• contribution workflow.

Consuming project#

A real project imports only what it needs.

Example:

my-api/
├── AGENTS.md
├── GOVERNANCE.md
├── PROJECT.md
├── .governance/
│   ├── manifest.yaml
│   ├── policies/
│   │   ├── security.md
│   │   └── validation.md
│   └── workflows/
│       └── implementation.md
├── src/
└── tests/

APG should not create governance bloat.

36. Example — Multi-Domain Project#

A larger organization may use:

company-project/
├── AGENTS.md
├── GOVERNANCE.md
├── PROJECT.md
│
├── product/
│   └── AGENTS.md
│
├── software/
│   ├── AGENTS.md
│   ├── frontend/
│   │   └── AGENTS.md
│   └── backend/
│       └── AGENTS.md
│
├── infrastructure/
│   ├── AGENTS.md
│   ├── ansible/
│   │   └── AGENTS.md
│   └── kubernetes/
│       └── AGENTS.md
│
├── documentation/
│   └── AGENTS.md
│
└── hr/
    └── AGENTS.md

Each subtree can specialize its own operating rules while inheriting repository governance.

This is the intended mechanism for allowing one framework to support very different domains without pretending that all domains share the same workflow.

37. Versioning Model#

Proposed framework versioning:

MAJOR.MINOR.PATCH

Example:

1.0.0
1.1.0
2.0.0

Starting with 1.0.0, breaking changes to core governance semantics require a major version.

A consuming project should record the APG specification version it targets:

spec_version: "1.0"

38. Compatibility Philosophy#

APG should distinguish three levels:

Core compatibility#

The project follows APG structure and governance semantics.

Adapter compatibility#

A specific AI tool can discover and use the project contract conveniently.

Native feature compatibility#

APG takes advantage of tool-specific capabilities such as:

• hierarchical instructions;
• imports;
• path matching;
• skills;
• hooks;
• generated context.

Native features may improve usability but must not be required to understand the core project contract.

39. Security Principles#

APG governance files should never become a secret store.

Do not place:

passwords
API keys
private keys
access tokens
production credentials
sensitive personal data

inside reusable governance documents.

Governance may reference a secrets-management mechanism but should not contain the secret itself.

Adapters must not duplicate sensitive runtime data.

40. Staleness Model#

Project knowledge has different lifetimes.

Recommended classification:

Governance       -> slow-changing
Project identity -> slow-changing
Architecture     -> medium-changing
Workflow         -> medium-changing
Current state    -> fast-changing
Task             -> temporary
Evidence         -> execution-specific

Fast-changing information should identify recency.

Example:

# Current State

Last Updated: 2026-08-17
Owner: Platform Team

Agents should avoid treating stale operational state as authoritative.

41. Authoring Rules#

Governance files should:

• use clear imperative language;
• define scope;
• distinguish MUST / SHOULD / MAY where useful;
• avoid ambiguous pronouns;
• avoid duplicated rules;
• link to canonical policy instead of copying it;
• state approval requirements explicitly;
• state validation requirements explicitly;
• identify what happens when a requirement cannot be satisfied;
• stay short enough to remain reviewable.

Governance files should not:

• contain motivational filler;
• contain hidden assumptions;
• depend on chat history;
• mix unrelated domains;
• repeat the same policy in multiple adapters;
• claim capabilities that the actual runtime cannot enforce.

42. Recommended Normative Keywords#

APG documentation may use:

MUST
MUST NOT
SHOULD
SHOULD NOT
MAY

Their exact normative interpretation should be documented in the future formal specification.

In v1.0, they are used conservatively and consistently.

43. Governance Change Rules#

Changes to the governance model are more significant than normal content changes.

Recommended rule classes:

Non-breaking#

Examples:

• typo;
• clarification;
• new example;
• new optional profile;
• new adapter that does not change core semantics.

Potentially breaking#

Examples:

• precedence change;
• authority model change;
• manifest schema change;
• meaning of inheritance;
• required file removal;
• change to protected-policy semantics.

Potentially breaking changes should require explicit specification review.

44. Decision Records#

Important architectural choices should be recorded rather than repeatedly debated.

Suggested future structure:

docs/decisions/
├── 0001-vendor-neutral-core.md
├── 0002-agents-as-router.md
├── 0003-policy-context-separation.md
└── 0004-root-to-leaf-scope.md

A decision record should include:

Status
Context
Decision
Consequences
Alternatives

Decision records are included in v1.0 without changing core semantics.

45. Proposed Initial Decisions#

The following decisions define the v1.0 baseline.

D-001 — Vendor-neutral canonical core#

Decision: Project governance must not depend on one model vendor.

D-002 — Repository-native contract#

Decision: Durable governance and project knowledge live with the project repository.

D-003 — AGENTS.md is a router#

Decision: AGENTS.md is an entry point and scoped instruction mechanism, not a dumping ground for all project knowledge.

D-004 — Separate policy, workflow, context, role, and task#

Decision: Each class of information has independent ownership and lifecycle.

D-005 — Root-to-leaf scoping#

Decision: Project subtrees may introduce increasingly specific instructions.

D-006 — Protected constraints cannot be silently weakened#

Decision: Specificity alone does not grant authority to bypass parent governance.

D-007 — Evidence-bound validation#

Decision: Validation claims require evidence.

D-008 — Minimal consumption#

Decision: Real projects import only the governance components they need.

D-009 — Thin adapters#

Decision: Vendor-specific files route into canonical governance rather than duplicating it.

D-010 — No runtime dependency#

Decision: The framework remains understandable and useful without installing a program.

46. v1.0.0 Release Scope#

The first public version should include only the features necessary to demonstrate the model completely.

Required#

README
GOVERNANCE
PROJECT
root AGENTS
manifest
core policies
core workflows
context examples
role examples
templates
three project examples
four adapter examples
two small shell tools
architecture documentation
instruction-resolution documentation
prior-art documentation
GitHub contribution files

Explicitly deferred#

MCP integration
agent orchestration
remote memory
vector storage
central policy server
automatic context embedding
complex CLI
Python package
npm package
GUI
SaaS service
multi-repository federation
organization policy distribution
signed governance bundles
policy-as-code engine

47. Suggested Roadmap#

v1.0 — Initial Public Release#

Establish the repository contract, governance semantics, bilingual guide, reference implementation, examples, adapters, bootstrap tool, validator, and GitHub Pages publication model.

v1.1 — Validation and Adapters#

Possible additions:

• stronger structural validation;
• adapter generation;
• machine-readable schema validation;
• additional compatibility tests.

v1.2 — Profile Ecosystem#

Possible additions:

• security;
• data;
• documentation;
• product;
• HR;
• research;
• industrial engineering.

v2.0 — Cross-Repository Governance#

Research areas:

• organization-level inheritance;
• shared policy packs;
• version pinning;
• dependency resolution;
• signed governance bundles.

Post-1.0 maturity goals#

• proven use in multiple real projects and domains;
• stable inheritance semantics;
• tool-independent compatibility tests;
• documented migration rules;
• community review and external contributions.

48. Success Criteria#

APG is successful if a new human or AI agent can enter an unfamiliar repository and answer:

What is this project?
What am I allowed to do?
What am I not allowed to do?
Which rules apply here?
What context do I need?
Which workflow should I follow?
Who owns the decision?
What evidence is required?
How do I report the result?

without requiring the original author to explain the entire project through chat.

49. Conceptual Summary#

                    PROJECT
                       │
          ┌────────────┼────────────┐
          │            │            │
          ▼            ▼            ▼
     Governance     Definition   Instructions
          │                         │
          │                   Root → Scoped
          │                         │
          └────────────┬────────────┘
                       ▼
                   Resolver
                       │
        ┌──────────────┼──────────────┐
        ▼              ▼              ▼
     Policies       Workflows       Context
        │              │              │
        └──────────────┼──────────────┘
                       ▼
                      Role
                       │
                       ▼
                      Task
                       │
                       ▼
                   Execution
                       │
                       ▼
                   Validation
                       │
                       ▼
                    Evidence
                       │
                       ▼
                Report / Handover

The important abstraction is:

The AI is replaceable. The project contract is durable.

50. One-Sentence Definition#

Agentic Project Governance is a vendor-neutral, repository-native structure for defining how humans and AI agents understand, govern, execute, validate, and hand over work within a project.

51. Post-1.0 Design Questions#

The v1.0 baseline is intentionally small. Future versions may evaluate:

1. Should APG define a formal RFC process for core semantic changes?
2. How should organization-level policy inheritance work across repositories?
3. Should governance bundles support signatures or integrity metadata?
4. When should the shell validator be complemented by a portable structured validator?
5. Which additional domain profiles provide enough reusable value to belong in the reference repository?

These questions do not block v1.0 adoption.

52. v1.0 Baseline#

For the first implementation, the recommended choices are:

Project name:          Agentic Project Governance
Canonical directory:  .governance/
Manifest:              Required
AGENTS front matter:   Optional
Roles:                 Included but optional to consuming projects
Adapters:              Codex, Claude, Gemini, Copilot examples
Decision records:      Include initial architecture decisions
Tooling:               Small POSIX-style shell bootstrap + validator
Runtime dependency:    None
Core format:           Markdown + YAML

This baseline is small enough to implement and complete enough to demonstrate the framework's real value.

End of v1.0.0#

Author#

Ahmad Sheikhi
Senior DevOps Engineer
Initial Author & Maintainer — Agentic Project Governance (APG)

Copyright © 2026 Ahmad Sheikhi.